Add Codex repository guidance and validation

scripts/check-docs.sh

@@ -0,0 +1,88 @@
+#!/usr/bin/env bash
+set -o errexit
+set -o nounset
+set -o pipefail
+
+STRICT="${STRICT:-0}"
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+
+ok_count=0
+warn_count=0
+fail_count=0
+
+ok() {
+  printf 'OK: %s\n' "$*"
+  ok_count=$((ok_count + 1))
+}
+
+warning() {
+  printf 'WARNING: %s\n' "$*"
+  warn_count=$((warn_count + 1))
+}
+
+critical() {
+  printf 'CRITICAL: %s\n' "$*"
+  fail_count=$((fail_count + 1))
+}
+
+mapfile -t markdown_files < <(find "$ROOT_DIR" -path "$ROOT_DIR/.git" -prune -o -type f -name '*.md' -print | sort)
+
+if ((${#markdown_files[@]} == 0)); then
+  warning "No Markdown files found"
+else
+  ok "Found ${#markdown_files[@]} Markdown files"
+fi
+
+missing_links=0
+while IFS= read -r link; do
+  [[ -n "$link" ]] || continue
+  file="${link%%:*}"
+  target="${link#*:}"
+
+  [[ "$target" == http://* || "$target" == https://* || "$target" == mailto:* || "$target" == \#* ]] && continue
+  target="${target%%#*}"
+  [[ -n "$target" ]] || continue
+
+  base_dir="$(dirname "$file")"
+  if [[ ! -e "$base_dir/$target" ]]; then
+    critical "Broken local Markdown link in ${file#"$ROOT_DIR"/}: $target"
+    missing_links=$((missing_links + 1))
+  fi
+done < <(
+  for file in "${markdown_files[@]}"; do
+    grep -Eo '\[[^]]+\]\([^)]+\)' "$file" \
+      | sed -E 's/.*\]\(([^)]+)\).*/'"${file//\//\\/}"':\1/' || true
+  done
+)
+
+if ((missing_links == 0)); then
+  ok "No obvious broken local Markdown links"
+fi
+
+if command -v markdownlint >/dev/null 2>&1; then
+  if markdownlint "${markdown_files[@]}"; then
+    ok "markdownlint"
+  else
+    critical "markdownlint reported issues"
+  fi
+elif command -v markdownlint-cli2 >/dev/null 2>&1; then
+  if markdownlint-cli2 "${markdown_files[@]}"; then
+    ok "markdownlint-cli2"
+  else
+    critical "markdownlint-cli2 reported issues"
+  fi
+else
+  if [[ "$STRICT" == "1" ]]; then
+    critical "markdownlint not installed"
+  else
+    warning "markdownlint not installed; skipped optional Markdown lint"
+  fi
+fi
+
+printf '\nDocs summary: %d OK, %d WARNING, %d CRITICAL\n' "$ok_count" "$warn_count" "$fail_count"
+
+if ((fail_count > 0)); then
+  exit 1
+fi
+
+exit 0