auto generating reference front-matter

src/personal_mcp/skills/document_loader.py

@@ -258,6 +258,51 @@ def _normalize_docs_path(path: str) -> str:
     return normalized.as_posix()
 
 
+def _title_from_reference_filename(filename: str) -> str:
+    stem = PurePosixPath(filename).stem
+    normalized = stem.replace("-", " ").replace("_", " ").split()
+    if not normalized:
+        return stem
+    return " ".join(token.capitalize() for token in normalized)
+
+
+def _reference_id_from_filename(filename: str) -> str | None:
+    stem = PurePosixPath(filename).stem.strip().lower().replace("_", "-")
+    normalized = re.sub(r"[^a-z0-9-]+", "-", stem)
+    normalized = re.sub(r"-+", "-", normalized).strip("-")
+    if not normalized:
+        return None
+    if not SKILL_ID_RE.fullmatch(normalized):
+        return None
+    return normalized
+
+
+def _discover_top_level_references(
+    *,
+    skill_dir: Traversable,
+) -> dict[str, ReferenceEntry]:
+    references_dir = skill_dir.joinpath("references")
+    if not references_dir.is_dir():
+        return {}
+
+    discovered: dict[str, ReferenceEntry] = {}
+    for child in sorted(references_dir.iterdir(), key=lambda item: item.name):
+        if child.is_dir() or not child.is_file():
+            continue
+        if not child.name.lower().endswith(".md"):
+            continue
+
+        ref_id = _reference_id_from_filename(child.name)
+        if ref_id is None:
+            continue
+
+        discovered[ref_id] = ReferenceEntry(
+            path=PurePosixPath("references").joinpath(child.name).as_posix(),
+            title=_title_from_reference_filename(child.name),
+        )
+    return discovered
+
+
 def _ensure_no_cycles(skills_by_id: dict[str, SkillRecord]) -> list[tuple[str, str]]:
     visiting: set[str] = set()
     visited: set[str] = set()
@@ -370,8 +415,11 @@ def load_docs_registry(
             )
             continue
 
+        effective_reference_entries = _discover_top_level_references(skill_dir=skill_dir)
+        effective_reference_entries.update(frontmatter.x_personal_mcp.references)
+
         references: dict[str, ReferenceRecord] = {}
-        for ref_id, ref_entry in frontmatter.x_personal_mcp.references.items():
+        for ref_id, ref_entry in effective_reference_entries.items():
             ref_relpath = skill_rel_root.joinpath(ref_entry.path).as_posix()
             if ref_relpath not in docs_markdown_by_path:
                 issues.append(