mcp-efficiency-engine 0.1.0 → 0.1.1

package/scripts/ops/llm-token-probe.py

@@ -17,9 +17,16 @@ from __future__ import annotations
 
 import argparse
 import os
+import sys
 from pathlib import Path
 from typing import List
 
+_REPO_ROOT = Path(__file__).resolve().parents[2]
+if str(_REPO_ROOT) not in sys.path:
+    sys.path.insert(0, str(_REPO_ROOT))
+
+from telemetry import build_telemetry_collector
+
 try:
     from openai import AzureOpenAI
 except Exception:
@@ -81,7 +88,10 @@ def main() -> int:
     args = parser.parse_args()
 
     repo_root = Path(args.repo_root)
+    collector = build_telemetry_collector(_REPO_ROOT)
     if not repo_root.exists():
+        collector.record_event("WarningGenerated", {"warning": "repo_root_missing", "repo_root": str(repo_root)}, level="WARNING")
+        collector.shutdown()
         print("prompt_tokens=0")
         print("completion_tokens=0")
         print("total_tokens=0")
@@ -99,6 +109,17 @@ def main() -> int:
     model = os.getenv("OPENAI_CHAT_MODEL", "gpt-4o-mini")
 
     if AzureOpenAI is None or not api_key or not endpoint:
+        collector.record_event(
+            "WarningGenerated",
+            {
+                "warning": "missing_credentials_or_openai_pkg",
+                "has_openai_pkg": AzureOpenAI is not None,
+                "has_api_key": bool(api_key),
+                "has_endpoint": bool(endpoint),
+            },
+            level="WARNING",
+        )
+        collector.shutdown()
         print("prompt_tokens=0")
         print("completion_tokens=0")
         print("total_tokens=0")
@@ -119,45 +140,88 @@ def main() -> int:
         "Devuelve un resumen tecnico corto con riesgos y evidencia."
     )
 
-    try:
-        response = client.chat.completions.create(
-            model=model,
-            messages=[
-                {"role": "system", "content": system_prompt},
-                {"role": "user", "content": user_prompt},
-            ],
-            temperature=0,
-            max_completion_tokens=400,
-        )
-
-        usage = response.usage
-        prompt_tokens = int(getattr(usage, "prompt_tokens", 0) or 0)
-        completion_tokens = int(getattr(usage, "completion_tokens", 0) or 0)
-        total_tokens = int(getattr(usage, "total_tokens", prompt_tokens + completion_tokens) or 0)
-
-        price_in = to_float(os.getenv("LLM_PRICE_INPUT_USD_PER_1K"), 0.0)
-        price_out = to_float(os.getenv("LLM_PRICE_OUTPUT_USD_PER_1K"), 0.0)
-        if price_in > 0 or price_out > 0:
-            cost = (prompt_tokens / 1000.0) * price_in + (completion_tokens / 1000.0) * price_out
-        else:
-            # fallback simple when split pricing is unknown
-            flat = to_float(os.getenv("LLM_PRICE_USD_PER_1K_TOKENS"), 0.0)
-            cost = (total_tokens / 1000.0) * flat if flat > 0 else 0.0
-
-        print(f"prompt_tokens={prompt_tokens}")
-        print(f"completion_tokens={completion_tokens}")
-        print(f"total_tokens={total_tokens}")
-        print(f"total_cost_usd={cost:.6f}")
-        print("probe_status=ok")
-        return 0
-
-    except Exception as ex:
-        print("prompt_tokens=0")
-        print("completion_tokens=0")
-        print("total_tokens=0")
-        print("total_cost_usd=0")
-        print(f"probe_status=error:{str(ex).replace(os.linesep, ' ')[:200]}")
-        return 0
+    with collector.start_execution(
+        operation="llm-token-probe",
+        session_id="ops",
+        provider="azure-openai",
+        model=model,
+    ):
+        with collector.start_span(name="provider.azure_openai_call", kind="CLIENT", attributes={"profile": args.profile}):
+            collector.record_event(
+                "LLMRequest",
+                {
+                    "provider": "azure-openai",
+                    "model": model,
+                    "profile": args.profile,
+                    "selected_files": len(files),
+                },
+            )
+            try:
+                response = client.chat.completions.create(
+                    model=model,
+                    messages=[
+                        {"role": "system", "content": system_prompt},
+                        {"role": "user", "content": user_prompt},
+                    ],
+                    temperature=0,
+                    max_completion_tokens=400,
+                )
+
+                usage = response.usage
+                prompt_tokens = int(getattr(usage, "prompt_tokens", 0) or 0)
+                completion_tokens = int(getattr(usage, "completion_tokens", 0) or 0)
+                total_tokens = int(getattr(usage, "total_tokens", prompt_tokens + completion_tokens) or 0)
+
+                price_in = to_float(os.getenv("LLM_PRICE_INPUT_USD_PER_1K"), 0.0)
+                price_out = to_float(os.getenv("LLM_PRICE_OUTPUT_USD_PER_1K"), 0.0)
+                if price_in > 0 or price_out > 0:
+                    cost = (prompt_tokens / 1000.0) * price_in + (completion_tokens / 1000.0) * price_out
+                else:
+                    # fallback simple when split pricing is unknown
+                    flat = to_float(os.getenv("LLM_PRICE_USD_PER_1K_TOKENS"), 0.0)
+                    cost = (total_tokens / 1000.0) * flat if flat > 0 else 0.0
+
+                collector.record_usage(
+                    input_tokens=prompt_tokens,
+                    output_tokens=completion_tokens,
+                    estimated_cost_usd=cost,
+                )
+                collector.record_event(
+                    "LLMResponse",
+                    {
+                        "provider": "azure-openai",
+                        "model": model,
+                        "prompt_tokens": prompt_tokens,
+                        "completion_tokens": completion_tokens,
+                        "total_tokens": total_tokens,
+                        "estimated_cost_usd": round(cost, 6),
+                    },
+                )
+
+                print(f"prompt_tokens={prompt_tokens}")
+                print(f"completion_tokens={completion_tokens}")
+                print(f"total_tokens={total_tokens}")
+                print(f"total_cost_usd={cost:.6f}")
+                print("probe_status=ok")
+                collector.shutdown()
+                return 0
+
+            except Exception as ex:
+                collector.record_event(
+                    "ExceptionThrown",
+                    {
+                        "provider": "azure-openai",
+                        "error": str(ex),
+                    },
+                    level="ERROR",
+                )
+                print("prompt_tokens=0")
+                print("completion_tokens=0")
+                print("total_tokens=0")
+                print("total_cost_usd=0")
+                print(f"probe_status=error:{str(ex).replace(os.linesep, ' ')[:200]}")
+                collector.shutdown()
+                return 0
 
 
 if __name__ == "__main__":

package/scripts/ops/telemetry-benchmark.py

@@ -0,0 +1,184 @@
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import statistics
+import subprocess
+import time
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+
+def utc_now() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+def build_command(python_exe: str) -> list[str]:
+    return [
+        python_exe,
+        "scripts/intake/resolve-routing.py",
+        "--input",
+        "telemetry benchmark",
+        "--intent",
+        "feature",
+        "--domain",
+        "backend",
+        "--source-type",
+        "code",
+        "--input-tokens",
+        "120",
+        "--output-tokens",
+        "45",
+        "--estimated-cost-usd",
+        "0.0032",
+        "--model",
+        "GPT-5.3-Codex",
+        "--local-tools",
+        "2",
+        "--remote-tools",
+        "1",
+    ]
+
+
+def run_variant(*, repo_root: Path, iterations: int, telemetry_enabled: bool, python_exe: str) -> dict[str, Any]:
+    durations_ms: list[float] = []
+    failures = 0
+    for _ in range(iterations):
+        env = os.environ.copy()
+        env["TELEMETRY_ENABLED"] = "true" if telemetry_enabled else "false"
+        env["TELEMETRY_EXPORTERS"] = "console,json"
+
+        start = time.perf_counter()
+        proc = subprocess.run(
+            build_command(python_exe),
+            cwd=str(repo_root),
+            env=env,
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+            check=False,
+        )
+        elapsed_ms = (time.perf_counter() - start) * 1000.0
+        durations_ms.append(elapsed_ms)
+        if proc.returncode != 0:
+            failures += 1
+
+    avg_ms = statistics.mean(durations_ms) if durations_ms else 0.0
+    p95_ms = statistics.quantiles(durations_ms, n=20)[18] if len(durations_ms) >= 20 else max(durations_ms, default=0.0)
+
+    return {
+        "telemetry_enabled": telemetry_enabled,
+        "iterations": iterations,
+        "failures": failures,
+        "avg_ms": round(avg_ms, 3),
+        "min_ms": round(min(durations_ms) if durations_ms else 0.0, 3),
+        "max_ms": round(max(durations_ms) if durations_ms else 0.0, 3),
+        "p95_ms": round(p95_ms, 3),
+    }
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Benchmark telemetry overhead on/off using resolve-routing as workload.")
+    parser.add_argument("--iterations", type=int, default=10)
+    parser.add_argument("--python", default="py")
+    parser.add_argument("--python-arg", default="-3")
+    parser.add_argument("--out", default="observability/evals/telemetry-overhead-benchmark.json")
+    args = parser.parse_args()
+
+    repo_root = Path(__file__).resolve().parents[2]
+    iterations = max(2, int(args.iterations))
+    python_exe = args.python
+
+    # Windows default launcher pattern: py -3
+    if args.python == "py" and args.python_arg:
+        python_exe = f"{args.python} {args.python_arg}"  # handled below
+
+    if " " in python_exe:
+        tokens = python_exe.split()
+        base = tokens[0]
+        extra = tokens[1:]
+    else:
+        base = python_exe
+        extra = []
+
+    def build_python() -> str:
+        if not extra:
+            return base
+        return base
+
+    # Probe python command in current environment.
+    probe = subprocess.run([base, *extra, "--version"], cwd=str(repo_root), stdout=subprocess.PIPE, stderr=subprocess.PIPE, check=False)
+    if probe.returncode != 0:
+        print("Unable to resolve python interpreter for benchmark")
+        return 1
+
+    def command_python() -> str:
+        return base
+
+    # Wrap variant runner to include optional extra interpreter args.
+    def run_with_variant(telemetry_enabled: bool) -> dict[str, Any]:
+        durations_ms: list[float] = []
+        failures = 0
+        for _ in range(iterations):
+            env = os.environ.copy()
+            env["TELEMETRY_ENABLED"] = "true" if telemetry_enabled else "false"
+            env["TELEMETRY_EXPORTERS"] = "console,json"
+            cmd = [base, *extra, *build_command(command_python())[1:]]
+
+            start = time.perf_counter()
+            proc = subprocess.run(
+                cmd,
+                cwd=str(repo_root),
+                env=env,
+                stdout=subprocess.DEVNULL,
+                stderr=subprocess.DEVNULL,
+                check=False,
+            )
+            elapsed_ms = (time.perf_counter() - start) * 1000.0
+            durations_ms.append(elapsed_ms)
+            if proc.returncode != 0:
+                failures += 1
+
+        avg_ms = statistics.mean(durations_ms) if durations_ms else 0.0
+        p95_ms = statistics.quantiles(durations_ms, n=20)[18] if len(durations_ms) >= 20 else max(durations_ms, default=0.0)
+
+        return {
+            "telemetry_enabled": telemetry_enabled,
+            "iterations": iterations,
+            "failures": failures,
+            "avg_ms": round(avg_ms, 3),
+            "min_ms": round(min(durations_ms) if durations_ms else 0.0, 3),
+            "max_ms": round(max(durations_ms) if durations_ms else 0.0, 3),
+            "p95_ms": round(p95_ms, 3),
+        }
+
+    enabled = run_with_variant(True)
+    disabled = run_with_variant(False)
+
+    overhead_ms = enabled["avg_ms"] - disabled["avg_ms"]
+    overhead_pct = ((overhead_ms / disabled["avg_ms"]) * 100.0) if disabled["avg_ms"] > 0 else 0.0
+
+    report = {
+        "timestamp": utc_now(),
+        "workload": "scripts/intake/resolve-routing.py",
+        "iterations": iterations,
+        "with_telemetry": enabled,
+        "without_telemetry": disabled,
+        "overhead": {
+            "avg_ms": round(overhead_ms, 3),
+            "avg_pct": round(overhead_pct, 3),
+        },
+    }
+
+    out_path = (repo_root / args.out).resolve()
+    out_path.parent.mkdir(parents=True, exist_ok=True)
+    out_path.write_text(json.dumps(report, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+
+    print(json.dumps(report, indent=2, ensure_ascii=False))
+    print(f"Benchmark report: {out_path}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/scripts/wiki/compiler_main.py

@@ -1,9 +1,16 @@
 import json
 import os
+import sys
 from datetime import datetime, timezone
 from pathlib import Path
 from typing import Any, Dict, List
 
+_REPO_ROOT = Path(__file__).resolve().parents[2]
+if str(_REPO_ROOT) not in sys.path:
+    sys.path.insert(0, str(_REPO_ROOT))
+
+from telemetry import build_telemetry_collector
+
 from orchestrator.wiki.graph_consolidator import GraphConsolidator
 from orchestrator.wiki.incremental_engine import IncrementalEngine
 from orchestrator.wiki.plugin_manager import PluginManager
@@ -106,82 +113,107 @@ def _write_routing_event(
 def main() -> int:
     start = datetime.now(timezone.utc)
     env_snapshot = _read_session_env()
-
-    manager = PluginManager()
-    include_external = str(os.getenv("AUTODOCS_INCLUDE_EXTERNAL_PROVIDERS", "")).strip().lower() in {
-        "1",
-        "true",
-        "yes",
-        "on",
-    }
-
-    # Keep CI output deterministic: external providers depend on local intake artifacts that
-    # may not exist on clean runners.
-    if include_external:
-        manager.register_provider(CodeGraphProvider(REPO_ROOT / "repo-intake" / "generated"))
-        manager.register_provider(GraphifyProvider(REPO_ROOT / "repo-intake" / "generated"))
-
-    manager.register_provider(RepoContentProvider(REPO_ROOT))
-
-    provider_result = manager.gather_all()
-    contracts = provider_result.get("contracts", [])
-    provider_errors = provider_result.get("errors", [])
-
-    consolidator = GraphConsolidator(
-        output_graph_path=UNIFIED_GRAPH_PATH,
-        markdown_output_dir=MARKDOWN_OUTPUT_DIR,
-    )
-    unified_graph = consolidator.consolidate(contracts)
-    wiki_nodes = unified_graph.get("wiki_nodes", {})
-
-    incremental_engine = IncrementalEngine(UNIFIED_GRAPH_PATH)
-    diff = incremental_engine.diff(wiki_nodes)
-    dirty_nodes = diff.get("dirty_nodes", {})
-    deleted_nodes = diff.get("deleted_nodes", [])
-    cached_nodes = diff.get("cached_graph", {}).get("nodes", {})
-
-    validator = WikiValidator(SCHEMA_PATH)
-    validation_report = validator.validate(wiki_nodes)
-    validator.write_reports(
-        json_path=VALIDATION_REPORT_JSON,
-        markdown_path=VALIDATION_REPORT_MD,
-        report=validation_report,
-    )
-
-    project_stats = consolidator.project_dirty_nodes(
-        dirty_nodes=dirty_nodes,
-        deleted_nodes=deleted_nodes,
-        all_nodes=wiki_nodes,
-        cached_nodes=cached_nodes,
-    )
-    consolidator.persist_graph(unified_graph)
-    consolidator.persist_manifests(unified_graph)
-
-    elapsed_ms = int((datetime.now(timezone.utc) - start).total_seconds() * 1000)
-    iteration_event: Dict[str, Any] = {
-        "timestamp": datetime.now(timezone.utc).isoformat(),
-        "source_type": "technical-docs",
-        "module": "autodocs",
-        "total_nodes": len(wiki_nodes),
-        "dirty_nodes": len(dirty_nodes),
-        "deleted_nodes": len(deleted_nodes),
-        "rendered_markdown": int(project_stats.get("rendered", 0)),
-        "deleted_markdown": int(project_stats.get("deleted", 0)),
-        "rendered_indexes": int(project_stats.get("indexes", 0)),
-        "rendered_manifests": int(project_stats.get("manifests", 0)),
-        "provider_errors": len(provider_errors),
-        "validation_errors": int(validation_report.get("summary", {}).get("error_count", 0)),
-        "validation_warnings": int(validation_report.get("summary", {}).get("warning_count", 0)),
-        "elapsed_ms": elapsed_ms,
-    }
-    _append_jsonl(ITERATION_LOG, iteration_event)
-    _write_routing_event(
-        env_snapshot=env_snapshot,
-        dirty_count=len(dirty_nodes),
-        total_nodes=len(wiki_nodes),
-        errors=provider_errors,
-        elapsed_ms=elapsed_ms,
-    )
+    collector = build_telemetry_collector(REPO_ROOT)
+
+    with collector.start_execution(operation="autodocs-compiler", session_id="autodocs"):
+        collector.record_event("ExecutionStarted", {"pipeline": "autodocs", "env_keys": sorted(env_snapshot.keys())})
+
+        manager = PluginManager(telemetry_collector=collector)
+        include_external = str(os.getenv("AUTODOCS_INCLUDE_EXTERNAL_PROVIDERS", "")).strip().lower() in {
+            "1",
+            "true",
+            "yes",
+            "on",
+        }
+
+        # Keep CI output deterministic: external providers depend on local intake artifacts that
+        # may not exist on clean runners.
+        if include_external:
+            manager.register_provider(CodeGraphProvider(REPO_ROOT / "repo-intake" / "generated"))
+            manager.register_provider(GraphifyProvider(REPO_ROOT / "repo-intake" / "generated"))
+
+        manager.register_provider(RepoContentProvider(REPO_ROOT))
+
+        with collector.start_span(name="autodocs.providers", kind="INTERNAL"):
+            provider_result = manager.gather_all()
+            contracts = provider_result.get("contracts", [])
+            provider_errors = provider_result.get("errors", [])
+            collector.record_metric("provider_calls", float(len(contracts) + len(provider_errors)), unit="count")
+
+        consolidator = GraphConsolidator(
+            output_graph_path=UNIFIED_GRAPH_PATH,
+            markdown_output_dir=MARKDOWN_OUTPUT_DIR,
+            telemetry_collector=collector,
+        )
+        with collector.start_span(name="autodocs.consolidate", kind="INTERNAL"):
+            unified_graph = consolidator.consolidate(contracts)
+            wiki_nodes = unified_graph.get("wiki_nodes", {})
+
+        incremental_engine = IncrementalEngine(UNIFIED_GRAPH_PATH, telemetry_collector=collector)
+        with collector.start_span(name="autodocs.incremental", kind="INTERNAL"):
+            diff = incremental_engine.diff(wiki_nodes)
+            dirty_nodes = diff.get("dirty_nodes", {})
+            deleted_nodes = diff.get("deleted_nodes", [])
+            cached_nodes = diff.get("cached_graph", {}).get("nodes", {})
+
+        validator = WikiValidator(SCHEMA_PATH, telemetry_collector=collector)
+        with collector.start_span(name="autodocs.validate", kind="INTERNAL"):
+            validation_report = validator.validate(wiki_nodes)
+            validator.write_reports(
+                json_path=VALIDATION_REPORT_JSON,
+                markdown_path=VALIDATION_REPORT_MD,
+                report=validation_report,
+            )
+
+        with collector.start_span(name="autodocs.project", kind="INTERNAL"):
+            project_stats = consolidator.project_dirty_nodes(
+                dirty_nodes=dirty_nodes,
+                deleted_nodes=deleted_nodes,
+                all_nodes=wiki_nodes,
+                cached_nodes=cached_nodes,
+            )
+            consolidator.persist_graph(unified_graph)
+            consolidator.persist_manifests(unified_graph)
+
+        elapsed_ms = int((datetime.now(timezone.utc) - start).total_seconds() * 1000)
+        iteration_event: Dict[str, Any] = {
+            "timestamp": datetime.now(timezone.utc).isoformat(),
+            "source_type": "technical-docs",
+            "module": "autodocs",
+            "total_nodes": len(wiki_nodes),
+            "dirty_nodes": len(dirty_nodes),
+            "deleted_nodes": len(deleted_nodes),
+            "rendered_markdown": int(project_stats.get("rendered", 0)),
+            "deleted_markdown": int(project_stats.get("deleted", 0)),
+            "rendered_indexes": int(project_stats.get("indexes", 0)),
+            "rendered_manifests": int(project_stats.get("manifests", 0)),
+            "provider_errors": len(provider_errors),
+            "validation_errors": int(validation_report.get("summary", {}).get("error_count", 0)),
+            "validation_warnings": int(validation_report.get("summary", {}).get("warning_count", 0)),
+            "elapsed_ms": elapsed_ms,
+        }
+        _append_jsonl(ITERATION_LOG, iteration_event)
+        _write_routing_event(
+            env_snapshot=env_snapshot,
+            dirty_count=len(dirty_nodes),
+            total_nodes=len(wiki_nodes),
+            errors=provider_errors,
+            elapsed_ms=elapsed_ms,
+        )
+
+        collector.record_metric("execution_time_ms", float(elapsed_ms), unit="ms")
+        collector.record_metric("warning_count", float(len(provider_errors)), unit="count")
+        collector.record_event(
+            "KnowledgeGenerated",
+            {
+                "total_nodes": len(wiki_nodes),
+                "dirty_nodes": len(dirty_nodes),
+                "deleted_nodes": len(deleted_nodes),
+                "elapsed_ms": elapsed_ms,
+            },
+        )
+
+    collector.shutdown()
 
     if int(validation_report.get("summary", {}).get("error_count", 0)) > 0:
         return 1

package/scripts/wiki/providers/repo_content_provider.py

@@ -14,6 +14,7 @@ class RepoContentProvider(BaseWikiProvider):
 
     def gather_knowledge(self) -> Dict[str, Any]:
         entities: List[Dict[str, Any]] = []
+        entities.extend(self._collect_core_docs())
         entities.extend(self._collect_agents())
         entities.extend(self._collect_skills())
         entities.extend(self._collect_policies())
@@ -25,6 +26,42 @@ class RepoContentProvider(BaseWikiProvider):
         self._enrich_relations(entities)
         return {"provider_id": self.provider_id, "entities": entities}
 
+    def _collect_core_docs(self) -> List[Dict[str, Any]]:
+        targets: List[Tuple[Path, str]] = [
+            (self.repo_root / "README.md", "Guia principal del engine y sus flujos operativos."),
+            (self.repo_root / "README_WIKI.md", "Guia de uso y alcance de la wiki AutoDocs del repositorio."),
+            (self.repo_root / "FINAL_USAGE_GUIDE.md", "Guia de uso final con pasos operativos y buenas practicas."),
+            (self.repo_root / "FILE_INDEX.md", "Indice del contenido y estructura del repositorio."),
+            (self.repo_root / "autodocs" / "README.md", "Referencia de ejecucion y artefactos de AutoDocs."),
+        ]
+
+        entities: List[Dict[str, Any]] = []
+        for path, fallback_summary in targets:
+            if not path.exists():
+                continue
+            entities.append(
+                self._entity_from_markdown(
+                    path,
+                    kind="report",
+                    section="reports",
+                    domain="documentation",
+                    fallback_summary=fallback_summary,
+                )
+            )
+
+        package_json = self.repo_root / "package.json"
+        if package_json.exists():
+            entities.append(
+                self._entity_from_json(
+                    package_json,
+                    kind="report",
+                    section="reports",
+                    domain="packaging",
+                )
+            )
+
+        return entities
+
     def _collect_agents(self) -> List[Dict[str, Any]]:
         agents_dir = self.repo_root / ".github" / "agents"
         if not agents_dir.exists():
@@ -292,6 +329,18 @@ class RepoContentProvider(BaseWikiProvider):
             for target_id in ["AGENTS.md", "orchestrator/router.md"]:
                 if target_id in entities_by_id:
                     self._add_relation(entity, target_id, "explains")
+        if source_ref == "README.md":
+            for target_id in ["AGENTS.md", "ARCHITECTURE.md", "FINAL_USAGE_GUIDE.md", "package.json"]:
+                if target_id in entities_by_id:
+                    self._add_relation(entity, target_id, "documents")
+        if source_ref == "FINAL_USAGE_GUIDE.md":
+            for target_id in ["README.md", "scripts/README.md"]:
+                if target_id in entities_by_id:
+                    self._add_relation(entity, target_id, "extends")
+        if source_ref == "autodocs/README.md":
+            for target_id in ["README_WIKI.md", "scripts/wiki/wiki_compiler.py"]:
+                if target_id in entities_by_id:
+                    self._add_relation(entity, target_id, "documents")
         if source_ref == "autodocs/analysis_mcpee/OPENWIKI_INTERNAL_BLUEPRINT.md":
             for target_id in ["autodocs/README.md", "README_WIKI.md"]:
                 if target_id in entities_by_id:
@@ -364,6 +413,8 @@ class RepoContentProvider(BaseWikiProvider):
         stem = path.name
         if path.name.lower() == "skill.md" and path.parent.name:
             stem = path.parent.name
+        elif path.stem.lower() == "readme" and path.parent != self.repo_root:
+            stem = f"{path.parent.name}-{path.name}"
         tokens = [kind, stem]
         if kind == "report" and "analysis_mcpee" in relative:
             tokens.insert(1, "autodocs")