Add CI guardrails for docs, lint, and search updates

[VatsalSy]

Summary

• Add targeted maintenance guardrails based on recurring PR/review feedback around docs drift, markdown linting, and workflow resilience.
• Reduce review churn by failing fast on known regression patterns (stale docs, missing search DB artifacts, and accidental node_modules commits).

Changes Made

• Add scripts/check-phd-thesis-nav-docs.sh and run it in .github/workflows/jekyll.yml to keep PhD thesis nav behavior aligned with documentation.
• Pin MathJax to 3.2.2 in _layouts/default.html and document inline math authoring/escaping policy in AGENTS.md.
• Add .markdownlint-cli2.jsonc to explicitly enforce MD034 and ignore vendored markdown; normalize the localhost URL style in README.md.
• Improve .github/workflows/update-search.yml with warnings + GITHUB_STEP_SUMMARY entries when clone/artifact steps fail, and gate commit/push on search_db_available == true.
• Add CI guards in .github/workflows/jekyll.yml to block PR/push diffs that modify node_modules/**.

Testing

• npm run lint:md
• ./scripts/check-phd-thesis-nav-docs.sh
• ruby -e "require 'yaml'; YAML.load_file('.github/workflows/jekyll.yml'); puts 'jekyll workflow YAML OK'"

[coderabbitai]

📝 Walkthrough

Summary by CodeRabbit

• Chores

  • Added CI guardrails to block node_modules changes on PRs and pushes.
  • Added search database availability checks and workflow warnings/summaries.
  • Added CI verification that thesis navigation docs stay in sync.
  • Added markdownlint config and a new .gitignore entry.

• Documentation

  • Minor README formatting tweak for the local dev URL.
  • Documented math authoring policy and added a robust MathJax fallback (local first, CDN as fallback).

Walkthrough

Adds CI guardrails and validation, improves search-update robustness, introduces a Markdown lint config, documents MathJax loading and math authoring policy, adds a PhD-thesis nav/docs sync checker script, small README and .gitignore updates, and minor layout fallback logic for MathJax.

Changes

Cohort / File(s)	Summary
Jekyll CI workflow \.github/workflows/jekyll.yml	Increases checkout fetch depth to 0; adds PR and push guards that detect and fail on node_modules changes (skips initial push); inserts thesis-nav/docs validation step before Ruby setup; minor step reordering.
Search DB workflow \.github/workflows/update-search.yml	Adds warnings and workflow summary notes when cloning fails; introduces steps.copy-search-db with search_db_available output flag; warns/mutates outputs when repo/search_db.json missing; guards commit/push step to run only if DB available.
Docs & Math rendering AGENTS.md, _layouts/default.html	Documents MathJax loading policy (vendored/local first, pinned jsDelivr fallback with SRI) and math authoring policy (inline delimiters and escaping $); layout adds deferred local MathJax load with onerror fallback to CDN preserving crossorigin.
Validation script scripts/check-phd-thesis-nav-docs.sh	Adds script that verifies _layouts/default.html contains a hardcoded PhD thesis nav link and that AGENTS.md contains the corresponding descriptive phrase; exits non‑zero with targeted messages on mismatch.
Linting & formatting .markdownlint-cli2.jsonc, README.md	Adds Markdown lint config enabling MD034 and ignoring specified paths; README localhost URL wrapped in angle brackets (markup-only change).
Git ignore .gitignore	Adds .comphy to ignored paths.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• Update thesis content and refresh dependencies #10: Adds the thesis navigation link and AGENTS.md content that the new validation script expects — directly related.
• Skip search update when db missing #11: Modifies update-search.yml to skip commit/push when the search DB is missing; strongly related to the search-workflow guards added here.

Poem

🐇 I hopped through CI to check each gate,

node_modules kept out — tidy and great.
I safeguard math with a fallback sweet,
I sniff thesis links so docs and layout meet.
A tiny script, a lint, a clever tweak — hooray for a calm deploy day! 🎉

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately summarizes the main changes: adding CI guardrails for docs, linting, and search updates, which aligns with the primary objectives of the changeset.
Description check	✅ Passed	The description provides a clear, detailed overview of the changes directly related to the changeset, including summary, specific changes made, and testing performed.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch maintenance/pr-review-guardrails

---

No actionable comments were generated in the recent review. 🎉

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[Copilot]

Pull request overview

Adds CI/documentation guardrails to reduce recurring review churn around docs drift, markdown linting, workflow resilience, and preventing accidental node_modules commits.

Changes:

• Adds a CI script + workflow step to ensure PhD thesis navigation behavior stays in sync with documented guidance.
• Updates MathJax loading (pinned CDN) and documents inline-math authoring/escaping policy.
• Introduces markdownlint-cli2 configuration and improves search DB update workflow robustness + reporting.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
scripts/check-phd-thesis-nav-docs.sh	New guard script to keep nav behavior aligned with AGENTS documentation.
_layouts/default.html	Pins MathJax via CDN and clarifies inline-math behavior.
README.md	Normalizes localhost URL style to comply with MD034 (no bare URLs).
AGENTS.md	Documents MathJax source and inline-math authoring/escaping policy.
.markdownlint-cli2.jsonc	Adds explicit markdownlint-cli2 configuration + ignores.
.github/workflows/update-search.yml	Adds warnings/step-summary reporting and gates commit/push on search DB availability.
.github/workflows/jekyll.yml	Adds node_modules diff guards and runs the new thesis nav/docs sync check.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.