🔨 Add markdown link linter

.github/workflows/markdown-link-lint.yaml

@@ -0,0 +1,28 @@
+name: Markdown Link Validation
+
+on:
+  schedule:
+    - cron: '0 0 * * 1' # Every Monday at midnight
+  workflow_dispatch:
+
+jobs:
+  validate-links:
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v4
+
+    - name: Install uv
+      uses: astral-sh/setup-uv@v5
+      with:
+        enable-cache: true
+
+    - name: Set up Python
+      run: uv python install
+
+    - name: Install dependencies
+      run: uv sync --dev
+
+    - name: Validate links
+      run: make lint_links

.pre-commit-config.yaml

@@ -5,6 +5,12 @@ repos:
       - id: check-added-large-files
   - repo: local
     hooks:
+      - id: lint-links
+        name: Lint markdown links
+        entry: make lint_links
+        language: system
+        pass_filenames: false
+        always_run: true
       - id: make-fmt
         name: Run formatter (make fmt)
         entry: make fmt

CLAUDE.md

@@ -25,7 +25,8 @@ make fmt            # Run ruff formatter + JSON formatting
 make ruff           # Run ruff linter
 make vulture        # Find dead code
 make ty             # Run type checker
-make ci             # Run all CI checks (ruff, vulture, ty, import_lint, docs_lint, check_deps)
+make lint_links     # Check for broken links in markdown files (README, etc.)
+make ci             # Run all CI checks (ruff, vulture, ty, import_lint, docs_lint, check_deps, lint_links)
 
 # Dependencies
 uv sync             # Install dependencies (not pip install)

Makefile

@@ -249,6 +249,11 @@ docs_lint: ## Lint docs links
 	@cd docs && bun run lint:links
 	@echo "$(GREEN)✅Docs linting completed.$(RESET)"
 
+lint_links: ## Lint all markdown links using pytest-check-links
+	@echo "$(YELLOW)🔍Linting all markdown links with pytest-check-links...$(RESET)"
+	@find . -name "*.md" -not -path "./.venv/*" -not -path "./node_modules/*" -not -path "./docs/node_modules/*" | xargs uv run pytest -p no:cov -o "addopts=" --check-links --check-links-ignore "http://localhost:.*"
+	@echo "$(GREEN)✅Link linting completed.$(RESET)"
+
 agents_validate: ## Validate AGENTS.md content
 	@echo "$(YELLOW)🔍Validating AGENTS.md...$(RESET)"
 	@$(PYTHON) scripts/validate_agents_md.py
@@ -259,7 +264,7 @@ check_deps: install_tools ## Check for unused dependencies
 	@uv run deptry .
 	@echo "$(GREEN)✅Dependency check completed.$(RESET)"
 
-ci: ruff vulture import_lint ty docs_lint check_deps ## Run all CI checks (ruff, vulture, import_lint, ty, docs_lint)
+ci: ruff vulture import_lint ty docs_lint lint_links check_deps ## Run all CI checks (ruff, vulture, import_lint, ty, docs_lint, lint_links)
 	@echo "$(GREEN)✅CI checks completed.$(RESET)"
 
 ########################################################

README.md

@@ -51,7 +51,7 @@ Opinionated Python stack for fast development. The `saas` branch extends `main`
 | Referrals + Agent system | ❌ | ✅ |
 | Ralph Wiggum Agent Loop | ✅ | ✅ |
 
-[Full comparison](docs/branch_comparison.md)
+[Full comparison](manual_docs/branch_comparison.md)
 
 ## Quick Start
 
@@ -75,12 +75,12 @@ global_config.example_parent.example_child
 global_config.OPENAI_API_KEY
 ```
 
-[Full configuration docs](docs/configuration.md)
+[Full configuration docs](manual_docs/configuration.md)
 
 ## Credits
 
 This software uses the following tools:
-- [Cursor: The AI Code Editor](cursor.com)
+- [Cursor: The AI Code Editor](https://cursor.com)
 - [uv](https://docs.astral.sh/uv/)
 - [prek: Rust-based pre-commit framework](https://github.com/j178/prek)
 - [DSPY: Pytorch for LLM Inference](https://dspy.ai/)

pyproject.toml

@@ -103,3 +103,8 @@ omit = [
 
 [tool.coverage.report]
 show_missing = true
+
+[dependency-groups]
+dev = [
+    "pytest-check-links>=0.9.1",
+]