fix: address docs checker review findings

Check every link reference definition, decode destinations per CommonMark,
report correct lines for empty headings, autolinks and nested definitions,
reject symlinked record directories and wrong-case path components, and
refuse titles that cannot pass. Only top-level headings count (spec section 6).

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

internal/docs/refs.go

@@ -92,6 +92,18 @@ func parseRef(v string, body bool) (ref, string) {
 
 // exists reports why a repo-root path is not a regular file inside the repository.
 func (c *checker) exists(p string) string {
+	// Match each component's case exactly, so case-insensitive filesystems agree with Linux.
+	dir := c.root
+	for _, part := range strings.Split(p, "/") {
+		if part == "" || part == "." {
+			continue
+		}
+		entries, err := os.ReadDir(dir)
+		if err != nil || !slices.ContainsFunc(entries, func(e os.DirEntry) bool { return e.Name() == part }) {
+			return "target " + p + " does not exist"
+		}
+		dir = filepath.Join(dir, part)
+	}
 	real, err := filepath.EvalSymlinks(filepath.Join(c.root, filepath.FromSlash(p)))
 	if err != nil {
 		return "target " + p + " does not exist"
@@ -156,7 +168,7 @@ func (m *fm) checkRef(spec refSpec, v, self string) string {
 		return ""
 	case k&kFile == 0 && !(k&kAdr != 0 && adrPathRe.MatchString(v)) && !(k&kPlan != 0 && planPathRe.MatchString(v)):
 		return fmt.Sprintf("%q is not accepted here; accepts %s", v, k)
-	case v == self:
+	case r.path == self:
 		return "a record must not reference itself"
 	}
 	return m.c.exists(r.path)