Add maintenance guardrails for CI and local workflow

[VatsalSy]

Summary

• Add targeted maintenance guardrails to prevent recurring workflow and review regressions.
• Enforce local and CI checks around node_modules drift, markdown bare-link linting, and docs/content sync.

Changes Made

• Add a staged-file blocker for node_modules/** via /scripts/check-node-modules.sh and wire it through /.husky/pre-commit.
• Add npm scripts for check:node-modules and lint:md:fix.
• Extend /scripts/check-phd-thesis-nav-docs.sh to also verify aboutVatsal.md matches the fallback section in about.md.
• Sync about.md fallback content with aboutVatsal.md (location/email link block).
• Harden .github/workflows/update-search.yml clone behavior to fail fast and emit repository/branch/URL/error details to GITHUB_STEP_SUMMARY.
• Add markdown lint execution to .github/workflows/jekyll.yml and scope markdownlint config to MD034 (bare URL checks) to avoid blocking on unrelated legacy markdown debt.
• Add a MathJax update checklist to AGENTS.md and document local guardrail usage in README.md.

Testing

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

[coderabbitai]

Important

Review skipped

Review was skipped due to path filters

⛔ Files ignored due to path filters (1)

• Gemfile.lock is excluded by !**/*.lock

CodeRabbit blocks several paths by default. You can override this behavior by explicitly including those paths in the path filters. For example, including **/dist/** will override the default block on the dist directory, by removing the pattern from both the lists.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

📝 Walkthrough

Walkthrough

Adds CI guardrails (Node.js setup and Markdown lint step in Jekyll workflow), hardens the search update clone step with logging and error annotations, introduces Husky pre-commit + node_modules blocker, adds markdownlint config and scripts, enhances thesis/about sync checks, and updates documentation and badges.

Changes

Cohort / File(s)	Summary
CI: Jekyll workflow .github/workflows/jekyll.yml	Insert Node.js (v22.16.0) setup with npm cache and Markdown lint step (npm ci, npm run lint:md); reorder and reformat workflow steps; retain Ruby build and artifact upload.
CI: Search update workflow .github/workflows/update-search.yml	Replace checkout with single-branch git clone --branch "${SEARCH_BRANCH}", capture clone logs to CLONE_LOG, sanitize and annotate clone errors, write GITHUB_STEP_SUMMARY on failure, and exit non-zero on failure.
Pre-commit / node_modules guard .husky/pre-commit, scripts/check-node-modules.sh, package.json	Add Husky pre-commit hook that runs scripts/check-node-modules.sh; new script detects staged node_modules/** and fails with cleanup guidance; add check:node-modules npm script.
Markdown linting config & scripts .markdownlint-cli2.jsonc, package.json	Set "default": false in markdownlint config; add lint:md:fix npm script; integrate markdown lint step into CI.
Validation and nav/about checks scripts/check-phd-thesis-nav-docs.sh, AGENTS.md	Extend thesis/nav sync script to compare ABOUT source vs fallback (new ABOUT_* vars, temp files, diff-based failure); add MathJax Update Checklist to AGENTS.md (duplicated).
Documentation & content README.md, about.md, AGENTS.md	Add "Commit Guardrails" section and expand FE/BE/contributing docs in README; replace location/email badges in about.md; add checklist entries and minor edits in AGENTS.md.

Sequence Diagram(s)

mermaid
sequenceDiagram
participant Runner as Runner (GH Actions)
participant Git as Git (remote)
participant GHUI as GitHub Actions UI
Runner->>Git: git clone --branch "${SEARCH_BRANCH}" (stderr -> CLONE_LOG)
alt clone succeeds
Git-->>Runner: exit 0, repo copied
Runner->>Runner: create assets/js; set clone_ok=true
else clone fails
Git-->>Runner: non-zero, error in CLONE_LOG
Runner->>Runner: sanitize CLONE_ERROR from CLONE_LOG
Runner->>GHUI: create error annotation with repo/branch/URL and CLONE_ERROR
Runner->>Runner: write failure summary to GITHUB_STEP_SUMMARY
Runner->>Runner: output CLONE_LOG to stderr and exit 1
end

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• Add CI guardrails for docs, lint, and search updates #12: Overlaps on CI/workflow changes and thesis-nav validation script.
• Update thesis content and refresh dependencies #10: Modifies the same update-search clone/checkout logic.
• August update #5: Touches about.md and package.json scripts related to guardrails.

Poem

🐰 I hopped through hooks and linted trails,
Sniffed staged node_modules and sounded the bells,
Clones now log, errors sparkle bright,
Docs synced neat beneath moonlight,
Tiny rabbit applauds: commit with delight! 🎉

🚥 Pre-merge checks | ✅ 4

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately and concisely describes the main objective of the changeset: adding maintenance guardrails for CI and local workflows.
Description check	✅ Passed	The description is comprehensive and directly related to the changeset, clearly outlining the summary, changes made, and testing performed.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Merge Conflict Detection	✅ Passed	✅ No merge conflicts detected when merging into main

_{✏️ 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 comphy-mac/maintenance-guardrails

---

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

[coderabbitai]

Actionable comments posted: 1

🤖 Fix all issues with AI agents

In @.github/workflows/jekyll.yml:
- Around line 60-64: The workflow uses actions/setup-node@v4 with node-version:
"22" which can install a Node 22.x below the package.json engines.node minimum;
update the GitHub Actions job to ensure the Node runtime matches package.json by
either setting node-version to a minimum-compatible semver like "22.16" (or
"22.16.x") or create a .nvmrc at the repo root with the required version and
switch the setup-node step to use node-version-file: ".nvmrc"; reference the
actions/setup-node@v4 step and the node-version property as well as
package.json's engines.node when making the change.

[Copilot]

Pull request overview

This PR adds workflow “guardrails” to prevent common maintenance regressions (accidental node_modules commits, markdown bare-link linting, and docs/content drift), and improves CI visibility/failure behavior for the search DB update workflow.

Changes:

• Add local + CI protections against committing/changing node_modules/** (new script + husky hook + CI checks).
• Add markdown linting in CI, with markdownlint-cli2 scoped to MD034 (bare URLs) and a lint:md:fix helper script.
• Extend the existing docs sync script to also verify about.md fallback content matches aboutVatsal.md, and sync the content accordingly.
• Harden the search DB workflow clone step to fail fast and emit detailed diagnostics to the step summary.

Reviewed changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
scripts/check-phd-thesis-nav-docs.sh	Adds a drift check between aboutVatsal.md and the fallback section in about.md.
scripts/check-node-modules.sh	New script to block commits that stage changes under node_modules/.
package.json	Adds npm scripts for check:node-modules and lint:md:fix.
about.md	Syncs fallback “Find me” content to match aboutVatsal.md.
README.md	Documents the new local commit guardrails and cleanup steps.
AGENTS.md	Adds a MathJax update checklist and references guardrail scripts.
.markdownlint-cli2.jsonc	Disables all markdownlint rules except MD034 (bare URLs).
.husky/pre-commit	Adds a pre-commit hook to run the node_modules staged-change blocker.
.github/workflows/update-search.yml	Makes clone failures explicit and adds richer diagnostics to GITHUB_STEP_SUMMARY.
.github/workflows/jekyll.yml	Adds markdown linting to CI via Node setup + npm ci + npm run lint:md.

---

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

[coderabbitai]

Actionable comments posted: 1

🤖 Fix all issues with AI agents

In `@scripts/check-phd-thesis-nav-docs.sh`:
- Around line 63-77: The sed extraction that writes to "${tmp_about_fallback}"
currently uses the range "/^${ABOUT_HEADING}\$/,$p" which grabs to EOF and
causes false diffs; change the extraction to stop at the next top-level heading
or closing marker so only the fallback section is captured (e.g., use a sed
range that ends just before the next /^# / heading or switch to an awk pattern
that prints from /^${ABOUT_HEADING}$/ until the next /^# / and writes to
"${tmp_about_fallback}"), ensuring the variables ABOUT_HEADING and
ABOUT_FALLBACK_FILE and the temp file "${tmp_about_fallback}" are updated
accordingly so the diff compares only the intended fallback content.