Documentation: 126 broken internal links across 69 files in docs-site/ (37 missing pages)

[github-actions]

Problem

A systematic link audit of docs-site/ found 126 broken internal links across 69 files, all pointing to 37 missing pages. These broken links result in dead ends for users navigating the documentation site.

Missing Pages (37 unique files)

The following files are referenced but do not exist:

Missing File	Referenced From
advanced/compose.md	advanced/index.md, commands/advanced/compose.md
advanced/multi-context.md	advanced/index.md, vm-lifecycle/listing.md, commands/context/*
advanced/pruning.md	advanced/index.md, vm-lifecycle/deleting.md
advanced/quotas.md	vm-lifecycle/creating.md, getting-started/concepts.md, commands/storage/list.md, commands/vm/kill.md
advanced/ssh-keys.md	commands/keys/*, getting-started/concepts.md, commands/vm/connect.md
advanced/tags.md	batch/, commands/batch/, advanced/index.md
advanced/templates.md	vm-lifecycle/creating.md, commands/template/, advanced/
ai/do.md	ai/index.md
ai/natural-language.md	ai/index.md
api/core.md	getting-started/concepts.md
api/index.md	authentication/service-principal.md
authentication/index.md	getting-started/concepts.md, index.md, commands/keys/rotate.md
authentication/profiles.md	commands/context/*, commands/vm/new.md, commands/util/sync.md
bastion/connecting.md	bastion/security.md
bastion/cost.md	bastion/security.md
bastion/index.md	getting-started/concepts.md, commands/bastion/list.md, vm-lifecycle/*
bastion/overview.md	commands/advanced/ip-diagnostics.md
development/index.md	commands/keys/export.md, commands/util/update.md
environment/best-practices.md	commands/env/index.md
environment/import-export.md	commands/env/index.md
file-transfer/copy.md	commands/util/index.md, commands/util/cp.md
file-transfer/dotfiles.md	commands/util/sync.md
file-transfer/sync.md	commands/batch/sync.md
monitoring/cost.md	monitoring/top.md, many commands/*.md
monitoring/index.md	commands/util/index.md
monitoring/ps.md	commands/util/index.md
monitoring/status.md	commands/util/index.md
monitoring/w.md	commands/util/index.md
snapshots/index.md	commands/snapshot/*, getting-started/concepts.md
snapshots/restore.md	commands/snapshot/*
snapshots/scheduled.md	commands/snapshot/*
storage/shared-home.md	commands/storage/*
storage/status.md	commands/storage/*
troubleshooting/common-issues.md	troubleshooting/compound-naming.md
troubleshooting/connection.md	batch/parallel.md
troubleshooting/index.md	troubleshooting/compound-naming.md
vm-lifecycle/index.md	many files

High-Priority Broken Links

The most-broken links (by reference count) are:

• vm-lifecycle/index.md — referenced 10 times
• monitoring/cost.md — referenced 9 times
• authentication/profiles.md — referenced 7 times
• storage/shared-home.md — referenced 5 times

Fix Options

1. Create stub pages for all 37 missing files with minimal content pointing to existing pages
2. Update links to point to existing content (e.g., authentication/profiles.md → authentication/service-principal.md)
3. Combination: Create stubs for genuinely new pages, fix links for pages where content already exists elsewhere

Discovery Method

# Run from repo root to reproduce
find docs-site -name "*.md" -exec grep -l "\[" {} \; | xargs python3 -c "
import sys, os, re
# (check all relative links for file existence)
"

Generated by Documentation Freshness Checker