Refactor AGENTS.md from encyclopedia to map; move spec into docs/

Splits the 990-line AGENTS.md into a 184-line map (architecture,
where-to-find index, always-on invariants, capability matrix,
maintenance contract) plus 18 new docs/*.md files holding the deep
content per topic (storage, schema and query languages, indexes,
embeddings, branches/commits, runs, merge, changes, execution, policy,
server, CLI reference, audit, errors, CI, constants, v0.3.1 notes).

Adds scripts/check-agents-md.sh and a check_agents_md CI job that
verifies every docs/ link in AGENTS.md resolves and every doc in the
canonical set is linked. CLAUDE.md remains a symlink to AGENTS.md.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

scripts/check-agents-md.sh

@@ -0,0 +1,77 @@
+#!/usr/bin/env bash
+# Verify that AGENTS.md and docs/ 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.
+#
+# Exit non-zero on any drift.
+
+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
+
+# 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)
+if [[ -d docs/releases ]]; then
+  canonical+=("docs/releases/")
+fi
+
+# Extract docs/ links from AGENTS.md (markdown link form: (docs/...))
+linked=()
+while IFS= read -r line; do
+  linked+=("$line")
+done < <(grep -oE '\(docs/[^)]+\)' "$agents_file" | sed -E 's/^\(|\)$//g' | sort -u)
+
+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
+      fail=1
+    fi
+  else
+    if [[ ! -f "$path" ]]; then
+      echo "error: AGENTS.md links to missing file: $path" >&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
+      found=1
+      break
+    fi
+  done
+  if [[ "$found" -eq 0 ]]; then
+    echo "error: doc not linked from AGENTS.md: $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
+  exit 1
+fi
+
+echo "AGENTS.md ↔ docs/ links OK (${#linked[@]} links, ${#canonical[@]} docs)."