Skip to content

BROKEN LINKS FIX SUMMARY

Overview

This document summarizes the approach to fixing 1,104 pre-existing broken links identified in broken-links.json.

Issues Fixed

1. Zeus-Coordinator Test ✅

  • Issue: Package had test script but no test files
  • Fix: Created index.test.ts with comprehensive test coverage
  • Status: Complete

2. NPM Vulnerabilities ✅ (Partial)

  • Issue: 22 npm vulnerabilities
  • Fixes Applied:
  • Updated @modelcontextprotocol/sdk from ^0.5.0 to ^1.24.3 in apps/atlas-mcp-server
  • Updated electron from ^28.0.0 to ^39.2.6 in apps/mobius-companion
  • Updated @vercel/node from ^3.0.0 to ^5.5.15 in apps/api-gateway
  • Remaining: 20 vulnerabilities (mostly transitive dependencies requiring breaking changes)
  • Status: Reduced from 22 to 20 vulnerabilities

Patterns Identified

  1. Directory Links Without README Files
  2. Many links point to directories (e.g., /docs/04-TECHNICAL-ARCHITECTURE/economics/)
  3. These directories exist but lack README.md files

  4. Solution: Create README.md files or update links to point to specific files

  5. Incorrect Path Resolution

  6. Some links use absolute paths starting with /docs/ instead of relative paths

  7. Solution: Update links to use correct relative paths

  8. Moved/Renamed Files

  9. Files exist but in different locations than linked
  10. Examples:
    • Cathedral-Rulebook.md exists at docs/02-THEORETICAL-FOUNDATIONS/cathedrals/
    • HIVE-Operator-Handbook-v0.1.md exists at docs/05-IMPLEMENTATION/hive/
    • FOUNDING_AGENTS_SOVEREIGN_STACK.md exists at docs/04-TECHNICAL-ARCHITECTURE/overview/technical/

  11. Solution: Update links to point to correct locations

  12. Missing Files

  13. Some files referenced don't exist anywhere in the repository
  14. Solution: Either create placeholder files or remove/update the links

Top 10 Most Referenced Broken Paths

  1. /docs/10-ARCHIVES/root-files/07-reference/ACADEMIC_INDEX.md (19 references)
  2. /docs/whitepaper/Mobius-Yellow-Paper-Math-Edition.md (6 references)
  3. /docs/10-ARCHIVES/root-files/README.md (6 references)
  4. /docs/10-ARCHIVES/legacy/01-whitepapers/archive/GIC_Whitepaper_v2.0.md (6 references)
  5. /docs/07-RESEARCH-AND-PUBLICATIONS/whitepapers/archive/GIC_Whitepaper_v2.0.md (6 references)
  6. /docs/03-architecture/technical/FOUNDING_AGENTS_SOVEREIGN_STACK.md (6 references)
  7. /docs/whitepaper/Chapter-07-Economics-of-Mobius.md (5 references)
  8. /docs/FOR-GOVERNMENTS (5 references - directory)
  9. /docs/FOR-ECONOMISTS (5 references - directory)
  10. /docs/FOR-ACADEMICS (5 references - directory)

Tools Created

Script: scripts/fix-broken-links.py

A Python script to systematically fix broken links by: - Finding files that exist in different locations - Calculating correct relative paths - Updating markdown files with corrected links

Usage: 

python3 scripts/fix-broken-links.py

Note: Review changes before committing, as some links may need manual verification.

  1. Create README Files for Directories
  2. Create README.md files for directories that are frequently linked

  3. Focus on: docs/04-TECHNICAL-ARCHITECTURE/economics/, docs/07-RESEARCH-AND-PUBLICATIONS/mic-economics/, etc.

  4. Run Link Checker Script

  5. Use the provided Python script to automatically fix links where files exist

  6. Manually review and fix remaining links

  7. Update Link Checker Configuration

  8. Ensure the link checker correctly resolves relative paths

  9. Update broken-links.json generation to handle directory links better

  10. Documentation Review

  11. Review frequently broken links to understand if they should be:
    • Fixed (file exists elsewhere)
    • Created (file should exist)
    • Removed (link is outdated)

Files That Need Attention

Missing Files to Create

  • docs/04-TECHNICAL-ARCHITECTURE/mii-spec.md (referenced in sentinels/README.md)
  • FORMAL_VERIFICATION.md (root level, referenced in sentinels/README.md)
  • Various README.md files in directories

Files That Exist But Are Linked Incorrectly

  • Cathedral-Rulebook.md - exists at docs/02-THEORETICAL-FOUNDATIONS/cathedrals/
  • HIVE-Operator-Handbook-v0.1.md - exists at docs/05-IMPLEMENTATION/hive/
  • FOUNDING_AGENTS_SOVEREIGN_STACK.md - exists at docs/04-TECHNICAL-ARCHITECTURE/overview/technical/

Status

  • ✅ Zeus-Coordinator test file created
  • ✅ NPM vulnerabilities reduced (22 → 20)
  • ⏳ Broken links fix script created (ready to run)
  • ⏳ Directory README files (to be created)
  • ⏳ Link updates (to be applied systematically)

Last Updated: 2025-12-06 Total Broken Links: 1,104 Fixed So Far: 0 (script ready, needs execution)