[BUG] Broken relative links across docs

[JasonTame]

Describe the bug
The docs site has widespread broken internal links caused by incorrect relative path depth. Astro/Starlight renders each markdown file as a directory-style URL (e.g. enterprise/apm-policy.md serves at /apm/enterprise/apm-policy/), so relative links resolve one level deeper than the source file's filesystem directory. Many links were written with too few ../ segments.

Examples:

• ./governance-guide/ on /apm/enterprise/apm-policy/ resolves to /apm/enterprise/apm-policy/governance-guide/ (404) — should be ../governance-guide/
• ../reference/targets-matrix/ on /apm/integrations/ide-tool-integration/ resolves to /apm/integrations/reference/targets-matrix/ (404) — should be ../../reference/targets-matrix/

Scale
A link checker script against the source markdown found:

• 462 broken relative links across 54 files (out of 890 relative links in 123 files)
• Affects cross-section links (../reference/, ../enterprise/, ../consumer/, etc.) and same-section sibling links (./sibling-page/)

Root cause
Every .md file at section/page.md renders at /section/page/, adding an extra URL segment. ./sibling/ from there resolves as /section/page/sibling/ (wrong) instead of /section/sibling/ (correct). The same off-by-one applies to all deeper ../ chains.

Why the build doesn't catch it
The starlight-links-validator plugin is configured with errorOnRelativeLinks: false, which skips validation of relative links entirely. It only validates absolute internal links (starting with /).

To reproduce

1. Visit https://microsoft.github.io/apm/enterprise/apm-policy/
2. Click "Governance Guide" → 404
3. Or visit https://microsoft.github.io/apm/integrations/ide-tool-integration/ → click "Targets matrix" → 404

Affected files (54 total)

Full file list with broken link counts

File	Broken links
consumer/deploy-a-bundle.md	8
consumer/drift-and-secure-by-default.md	3
consumer/governance-on-the-consumer-ramp.md	1
consumer/update-and-refresh.mdx	4
enterprise/adoption-playbook.md	17
enterprise/apm-policy.md	13
enterprise/drift-detection.md	5
enterprise/enforce-in-ci.md	8
enterprise/github-rulesets.md	7
enterprise/governance-guide.md	22
enterprise/lifecycle-scripts.md	1
enterprise/making-the-case.md	16
enterprise/policy-pilot.md	6
enterprise/policy-reference.md	6
enterprise/registry-proxy.md	11
enterprise/security.md	17
getting-started/authentication.md	6
getting-started/first-package.md	2
getting-started/installation.md	1
getting-started/migration.md	3
guides/registries.md	18
integrations/ide-tool-integration.md	26
producer/author-primitives/hooks-and-commands.md	5
producer/author-primitives/instructions-and-agents.md	4
producer/author-primitives/mcp-as-primitive.md	12
producer/author-primitives/prompts.md	4
producer/author-primitives/skills.md	4
producer/compile.md	12
producer/pack-a-bundle.md	10
producer/package-relative-links.md	1
producer/preview-and-validate.md	6
producer/publish-to-a-marketplace.md	13
producer/releasing-from-any-ci.md	1
producer/repo-shapes.md	6
producer/versioning-strategies.md	1
reference/baseline-checks.md	9
reference/cli/approve.md	1
reference/cli/pack.md	1
reference/environment-variables.md	7
reference/examples.md	4
reference/experimental.md	5
reference/lockfile-spec.md	8
reference/manifest-schema.md	20
reference/package-types.md	3
reference/policy-schema.md	7
reference/primitive-types.md	1
reference/registry-http-api.md	1
reference/targets-matrix.md	13
troubleshooting/common-errors.md	21
troubleshooting/compile-zero-output-warning.md	9
troubleshooting/install-failures.md	8
troubleshooting/migration.md	10
troubleshooting/policy-debugging.md	11
troubleshooting/ssl-issues.md	4

Expected behavior
All internal doc links resolve to the correct pages.

Environment

• OS: macOS
• Python Version: 3.10.20
• APM Version: 0.24.1

[JasonTame]

I'll raise a PR to fix the broken links for now, but it might be worth moving to absolute URLs to avoid this type of issue in the future? The link validator will be be able catch any regressions going forward.

[github-actions]

Triage Panel Verdict

Issue: [BUG] 462 broken relative links across 54 docs site pages

Panel Analysis

DevX UX Expert: This is the highest-impact docs usability issue in the queue. 462 broken links across 54 files means roughly half of all relative links in the docs are broken. Every user who clicks a cross-section link (e.g., "Governance Guide", "Targets matrix") hits a 404. The root cause is a systematic off-by-one: Starlight renders section/page.md at /section/page/, so all relative links need one more ../ than filesystem-relative authors typically write. The fix is mechanical and automatable. The reporter has already done the hard work of identifying all 54 affected files and 462 broken links.

Supply Chain Security Expert: No security surface. Documentation-only.

APM CEO: High priority. Broken navigation directly degrades the first-impression experience for new adopters -- "check the docs" is the standard response to questions, and 404s at that point break trust. The fix is well-scoped (rewrite 462 relative paths, enable errorOnRelativeLinks: true in starlight-links-validator to prevent regression). This should land in the next docs-site release.

Decision

Dimension	Value
Type	type/bug (existing)
Theme	theme/governance
Area	area/docs-site
Priority	priority/high -- 462 broken links, active user-facing 404s
Status	status/accepted -- root cause clear, fix scope well-defined
Milestone	None assigned at this time

Suggested next action: Use the reporter's broken-link inventory (54 files, 462 links) to run a batch rewrite adding the missing ../ prefix level to each broken relative link. After fixing, set errorOnRelativeLinks: true in the starlight-links-validator config to prevent regression. This is a good candidate for an automated script or good first issue if a contributor wants to tackle it.

---

Triage status: agentic proposal pending human ratification.
Silence is approval. Maintainers can:

• Override any label or milestone above by editing it directly --
  human edits are authoritative and will not be reverted on
  subsequent runs.
• Re-trigger triage by applying the status/needs-triage label, or
  by removing status/triaged to enroll the issue in the next
  daily sweep.

Posted by the Triage Panel workflow. See .apm/skills/apm-triage-panel for the panel skill.

Generated by Triage Panel · 98.3 AIC · ⌖ 8.66 AIC · ⊞ 9.2K · ◷