docs: split user and developer docs (#93)

scripts/check-agents-md.sh

@@ -1,77 +1,116 @@
 #!/usr/bin/env bash
-# Verify that AGENTS.md and docs/ stay in sync.
+# Verify that AGENTS.md and the docs audience indexes stay in sync.
 #
-# Two checks:
-#   1. Every docs/*.md path linked from AGENTS.md exists on disk.
-#   2. Every doc in the canonical set is linked from AGENTS.md.
+# Checks:
+#   1. Every docs/ link from AGENTS.md, docs/user/index.md, and
+#      docs/dev/index.md exists.
+#   2. Every canonical docs file is discoverable from those indexes.
 #
-# Exit non-zero on any drift.
+# Release notes are represented by the docs/releases/ directory entry instead
+# of requiring every per-version release note to be linked individually.
 
 set -euo pipefail
 
 repo_root="$(cd "$(dirname "$0")/.." && pwd)"
 cd "$repo_root"
 
-agents_file="AGENTS.md"
-if [[ ! -f "$agents_file" ]]; then
-  echo "error: $agents_file not found" >&2
-  exit 1
-fi
+index_files=(AGENTS.md docs/user/index.md docs/dev/index.md)
+for index_file in "${index_files[@]}"; do
+  if [[ ! -f "$index_file" ]]; then
+    echo "error: $index_file not found" >&2
+    exit 1
+  fi
+done
+
+normalize_path() {
+  python3 - "$1" <<'PY'
+import os
+import sys
+
+print(os.path.normpath(sys.argv[1]).replace(os.sep, "/"))
+PY
+}
 
-# Canonical set: every docs/*.md (top-level), plus the releases/ index dir if present.
 canonical=()
 while IFS= read -r line; do
   canonical+=("$line")
-done < <(find docs -mindepth 1 -maxdepth 1 -type f -name '*.md' | sort)
+done < <(find docs -type f -name '*.md' ! -path 'docs/releases/*' | sort)
 if [[ -d docs/releases ]]; then
   canonical+=("docs/releases/")
 fi
 
-# Extract docs/ links from AGENTS.md (markdown link form: (docs/...))
 linked=()
+for index_file in "${index_files[@]}"; do
+  base_dir="$(dirname "$index_file")"
+
+  # Markdown links.
+  while IFS= read -r raw_link; do
+    link="${raw_link%%#*}"
+    [[ -z "$link" ]] && continue
+    [[ "$link" =~ ^[a-zA-Z][a-zA-Z0-9+.-]*: ]] && continue
+    [[ "$link" == /* ]] && continue
+
+    if [[ "$link" == docs/* ]]; then
+      normalized="$(normalize_path "$link")"
+    else
+      normalized="$(normalize_path "$base_dir/$link")"
+    fi
+    if [[ "$link" == */ ]]; then
+      normalized="${normalized%/}/"
+    fi
+    linked+=("$normalized")
+  done < <(
+    grep -oE '\[[^]]+\]\([^)]+\)' "$index_file" \
+      | sed -E 's/.*\(([^)]+)\).*/\1/' || true
+  )
+
+  # Agent import directives in AGENTS.md.
+  while IFS= read -r raw_link; do
+    link="${raw_link#@}"
+    linked+=("$(normalize_path "$link")")
+  done < <(grep -oE '^@docs/[^[:space:]]+' "$index_file" || true)
+done
+
+deduped=()
 while IFS= read -r line; do
-  linked+=("$line")
-done < <(grep -oE '\(docs/[^)]+\)' "$agents_file" | sed -E 's/^\(|\)$//g' | sort -u)
+  deduped+=("$line")
+done < <(printf '%s\n' "${linked[@]}" | sort -u)
+linked=("${deduped[@]}")
 
 fail=0
 
-# Check 1: every linked path exists.
 for link in "${linked[@]}"; do
-  # Strip in-page anchors like #foo
-  path="${link%%#*}"
-  if [[ "$path" == */ ]]; then
-    if [[ ! -d "$path" ]]; then
-      echo "error: AGENTS.md links to missing directory: $path" >&2
+  if [[ "$link" == */ ]]; then
+    if [[ ! -d "$link" ]]; then
+      echo "error: docs index links to missing directory: $link" >&2
       fail=1
     fi
   else
-    if [[ ! -f "$path" ]]; then
-      echo "error: AGENTS.md links to missing file: $path" >&2
+    if [[ ! -f "$link" ]]; then
+      echo "error: docs index links to missing file: $link" >&2
       fail=1
     fi
   fi
 done
 
-# Check 2: every canonical doc is linked at least once.
 for doc in "${canonical[@]}"; do
   found=0
   for link in "${linked[@]}"; do
-    path="${link%%#*}"
-    if [[ "$path" == "$doc" ]]; then
+    if [[ "$link" == "$doc" ]]; then
       found=1
       break
     fi
   done
   if [[ "$found" -eq 0 ]]; then
-    echo "error: doc not linked from AGENTS.md: $doc" >&2
+    echo "error: doc not linked from AGENTS.md or audience indexes: $doc" >&2
     fail=1
   fi
 done
 
 if [[ "$fail" -ne 0 ]]; then
   echo >&2
-  echo "AGENTS.md / docs/ are out of sync. Either update AGENTS.md links or rename/remove the doc." >&2
+  echo "AGENTS.md / docs indexes are out of sync. Update AGENTS.md, docs/user/index.md, or docs/dev/index.md." >&2
   exit 1
 fi
 
-echo "AGENTS.md ↔ docs/ links OK (${#linked[@]} links, ${#canonical[@]} docs)."
+echo "AGENTS.md ↔ docs indexes OK (${#linked[@]} links, ${#canonical[@]} docs)."