deepdoc 2.2.0__tar.gz → 2.3.0__tar.gz

{deepdoc-2.2.0 → deepdoc-2.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: deepdoc
-Version: 2.2.0
+Version: 2.3.0
 Summary: Auto-generate beautiful docs from any codebase
 Author: Pranav Kumar
 License: MIT
@@ -43,6 +43,18 @@ Dynamic: license-file
 [![Python versions](https://img.shields.io/pypi/pyversions/deepdoc)](https://pypi.org/project/deepdoc/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
 
+## Repository Layout
+
+| Directory | What it is | Where to start |
+|---|---|---|
+| [`deepdoc/`](./deepdoc/) | The Python package — CLI, pipeline, planner, generator, chatbot, and site builder. This is the core product. | [`deepdoc/README.md`](./deepdoc/README.md) |
+| [`web/`](./web/) | Marketing and changelog site built with Astro 5 + Tailwind. Deployed to the public DeepDoc website. | [`web/README.md`](./web/README.md) |
+| [`vscode-extension/`](./vscode-extension/) | VS Code extension — explains selected code snippets in Fast or Deep mode and inserts AI-generated comments inline. | [`vscode-extension/README.md`](./vscode-extension/README.md) |
+| [`tests/`](./tests/) | pytest test suite for the Python package. | Run `python3 -m pytest -q` from repo root. |
+| [`scripts/`](./scripts/) | One-off release and maintenance scripts. | — |
+
+---
+
 Auto-generate deep engineering documentation from real codebases using AI.
 
 DeepDoc scans your repo, builds a bucket-based documentation plan, generates rich MDX pages with Mermaid diagrams, and builds a local-first Fumadocs site with Orama search.

{deepdoc-2.2.0 → deepdoc-2.3.0}/README.md

@@ -4,6 +4,18 @@
 [![Python versions](https://img.shields.io/pypi/pyversions/deepdoc)](https://pypi.org/project/deepdoc/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
 
+## Repository Layout
+
+| Directory | What it is | Where to start |
+|---|---|---|
+| [`deepdoc/`](./deepdoc/) | The Python package — CLI, pipeline, planner, generator, chatbot, and site builder. This is the core product. | [`deepdoc/README.md`](./deepdoc/README.md) |
+| [`web/`](./web/) | Marketing and changelog site built with Astro 5 + Tailwind. Deployed to the public DeepDoc website. | [`web/README.md`](./web/README.md) |
+| [`vscode-extension/`](./vscode-extension/) | VS Code extension — explains selected code snippets in Fast or Deep mode and inserts AI-generated comments inline. | [`vscode-extension/README.md`](./vscode-extension/README.md) |
+| [`tests/`](./tests/) | pytest test suite for the Python package. | Run `python3 -m pytest -q` from repo root. |
+| [`scripts/`](./scripts/) | One-off release and maintenance scripts. | — |
+
+---
+
 Auto-generate deep engineering documentation from real codebases using AI.
 
 DeepDoc scans your repo, builds a bucket-based documentation plan, generates rich MDX pages with Mermaid diagrams, and builds a local-first Fumadocs site with Orama search.

{deepdoc-2.2.0 → deepdoc-2.3.0}/deepdoc/__init__.py

@@ -1,3 +1,3 @@
 """DeepDoc — Auto-generate beautiful docs from any codebase."""
 
-__version__ = "2.1.0"
+__version__ = "2.2.1"

{deepdoc-2.2.0 → deepdoc-2.3.0}/deepdoc/changelog_writer.py

@@ -31,7 +31,7 @@ def record_and_write(
     files_changed: list[str],
     is_initial: bool = False,
 ) -> None:
-    """Append one changelog entry and regenerate whats-changed.mdx."""
+    """Append one changelog entry and regenerate whats-changed.md."""
     entry = {
         "commit": commit[:8],
         "run_at": datetime.now(timezone.utc).isoformat(timespec="seconds"),
@@ -47,15 +47,15 @@ def record_and_write(
 
 
 def write_whats_changed_page(repo_root: Path, output_dir: Path) -> None:
-    """Write docs/whats-changed.mdx from .deepdoc/changelog.json."""
+    """Write docs/whats-changed.md from .deepdoc/changelog.json."""
     entries = load_changelog(repo_root)
-    mdx = _build_mdx(entries)
+    content = _build_md(entries)
     output_dir.mkdir(parents=True, exist_ok=True)
-    atomic_write_text(output_dir / "whats-changed.mdx", mdx)
+    atomic_write_text(output_dir / "whats-changed.md", content)
     _ensure_in_nav(repo_root)
 
 
-def _build_mdx(entries: list[dict]) -> str:
+def _build_md(entries: list[dict]) -> str:
     lines = [
         "---",
         'title: "What\'s Changed"',
@@ -72,11 +72,11 @@ def _build_mdx(entries: list[dict]) -> str:
 
     if not entries:
         lines.append(
-            "<Callout>No changelog entries yet. Run `deepdoc generate` to create the first entry.</Callout>"
+            ":::note\nNo changelog entries yet. Run `deepdoc generate` to create the first entry.\n:::"
         )
         return "\n".join(lines)
 
-    lines.append("<Accordions>")
+    lines.append(":::accordions")
     for entry in entries:
         date = entry.get("date", "")
         msg = entry.get("commit_message", "update")
@@ -88,7 +88,7 @@ def _build_mdx(entries: list[dict]) -> str:
         strategy_label = _STRATEGY_LABEL.get(strategy, strategy)
 
         title = f"{date} — {msg[:72]} ({sha})"
-        lines.append(f'<Accordion title="{title}">')
+        lines.append(f'::accordion{{title="{title}"}}')
         lines.append("")
 
         # Commit metadata row
@@ -119,7 +119,7 @@ def _build_mdx(entries: list[dict]) -> str:
                     lines.append(f"- [{_slug_to_title(s)}](/{s})")
             else:
                 lines.append(
-                    "<Callout type='info'>No pages were regenerated — only metadata or chatbot corpora were refreshed.</Callout>"
+                    ":::info\nNo pages were regenerated — only metadata or chatbot corpora were refreshed.\n:::"
                 )
 
             # Source files that changed
@@ -148,9 +148,9 @@ def _build_mdx(entries: list[dict]) -> str:
                 )
 
         lines.append("")
-        lines.append("</Accordion>")
+        lines.append("::")
 
-    lines.append("</Accordions>")
+    lines.append(":::")
     return "\n".join(lines)
 
 

{deepdoc-2.2.0 → deepdoc-2.3.0}/deepdoc/chatbot/answer_mixin.py

@@ -7,6 +7,11 @@ import re
 from typing import Any, Callable
 
 from ..source_metadata import classify_source_kind
+from .constants import (
+    CODE_WORKSPACE_CONFIG_NAMES,
+    CODE_WORKSPACE_CONFIG_SUFFIXES,
+    CODE_WORKSPACE_SUFFIXES,
+)
 from .types import (
     EvidenceItem,
     ReferenceItem,
@@ -14,17 +19,6 @@ from .types import (
     RetrievedChunk,
 )
 
-CODE_WORKSPACE_SUFFIXES = {
-    ".py", ".js", ".jsx", ".ts", ".tsx", ".go", ".php", ".java", ".rb",
-    ".rs", ".vue", ".svelte", ".html", ".css", ".scss", ".sass",
-}
-CODE_WORKSPACE_CONFIG_NAMES = {
-    ".env", ".env.example", "docker-compose.yml", "docker-compose.yaml",
-    "package.json", "pyproject.toml", "requirements.txt", "composer.json",
-    "go.mod", "cargo.toml", "gemfile",
-}
-CODE_WORKSPACE_CONFIG_SUFFIXES = {".json", ".toml", ".yaml", ".yml", ".ini", ".cfg"}
-
 
 class AnswerMixin:
     """Mixin providing answer generation and evidence contract methods."""
@@ -1039,7 +1033,7 @@ class AnswerMixin:
                         {
                             "title": page.title,
                             "url": url,
-                            "doc_path": f"{page.slug}.mdx",
+                            "doc_path": f"{page.slug}.md",
                         },
                     )
         return list(links.values())[:5]

deepdoc-2.3.0/deepdoc/chatbot/constants.py

@@ -0,0 +1,27 @@
+"""Shared constants for the chatbot module."""
+
+from __future__ import annotations
+
+STOPWORD_TOKENS: frozenset[str] = frozenset({
+    "a", "an", "and", "any", "are", "can", "does", "first", "for", "from",
+    "handle", "handled", "how", "in", "is", "it", "its", "of", "or", "repo",
+    "repository", "show", "that", "the", "this", "to", "use", "what", "went",
+    "where", "who", "which", "with", "work",
+})
+
+DOC_SUFFIXES: frozenset[str] = frozenset({".md", ".mdx", ".txt", ".rst", ".adoc", ".ipynb"})
+
+CODE_WORKSPACE_SUFFIXES: frozenset[str] = frozenset({
+    ".py", ".js", ".jsx", ".ts", ".tsx", ".go", ".php", ".java", ".rb",
+    ".rs", ".vue", ".svelte", ".html", ".css", ".scss", ".sass",
+})
+
+CODE_WORKSPACE_CONFIG_NAMES: frozenset[str] = frozenset({
+    ".env", ".env.example", "docker-compose.yml", "docker-compose.yaml",
+    "package.json", "pyproject.toml", "requirements.txt", "composer.json",
+    "go.mod", "cargo.toml", "gemfile",
+})
+
+CODE_WORKSPACE_CONFIG_SUFFIXES: frozenset[str] = frozenset({
+    ".json", ".toml", ".yaml", ".yml", ".ini", ".cfg",
+})

{deepdoc-2.2.0 → deepdoc-2.3.0}/deepdoc/chatbot/docs_summary.py

@@ -548,8 +548,8 @@ def _looks_binary(path: Path) -> bool:
 def _doc_path_for_page(output_dir: Path, page: Any) -> Path:
     hints = (page._b.generation_hints or {}) if hasattr(page, "_b") else {}
     if hints.get("is_introduction_page") or page.page_type == "overview":
-        return output_dir / "index.mdx"
-    return output_dir / f"{page.slug}.mdx"
+        return output_dir / "index.md"
+    return output_dir / f"{page.slug}.md"
 
 
 def _doc_url(page: Any, has_openapi: bool) -> str:

{deepdoc-2.2.0 → deepdoc-2.3.0}/deepdoc/chatbot/indexer.py

@@ -316,14 +316,14 @@ class ChatbotIndexer:
                 changed_keys=artifact_targets,
                 deleted_keys=deleted_files,
             )
-        deleted_doc_paths = [path for path in deleted_files if path.endswith(".mdx")]
+        deleted_doc_paths = [path for path in deleted_files if path.endswith((".md", ".mdx"))]
         if rebuild_doc_summary:
             self._save_records("doc_summary", doc_summary_records)
         else:
             self._merge_records(
                 "doc_summary",
                 doc_summary_records,
-                changed_keys=[f"{slug}.mdx" for slug in changed_doc_slugs],
+                changed_keys=[f"{slug}.md" for slug in changed_doc_slugs],
                 deleted_keys=deleted_doc_paths,
             )
         if rebuild_doc_full:
@@ -332,7 +332,7 @@ class ChatbotIndexer:
             self._merge_records(
                 "doc_full",
                 doc_full_records,
-                changed_keys=[f"{slug}.mdx" for slug in changed_doc_slugs],
+                changed_keys=[f"{slug}.md" for slug in changed_doc_slugs],
                 deleted_keys=deleted_doc_paths,
             )
         if rebuild_repo_doc:

{deepdoc-2.2.0 → deepdoc-2.3.0}/deepdoc/chatbot/linking.py

@@ -67,8 +67,8 @@ def bucket_doc_path(bucket: DocBucket) -> str:
     hints = bucket.generation_hints or {}
     page_type = hints.get("prompt_style", bucket.bucket_type)
     if hints.get("is_introduction_page") or page_type == "overview":
-        return "index.mdx"
-    return f"{bucket.slug}.mdx"
+        return "index.md"
+    return f"{bucket.slug}.md"
 
 
 def bucket_doc_url(bucket: DocBucket, *, has_openapi: bool = False) -> str:

{deepdoc-2.2.0 → deepdoc-2.3.0}/deepdoc/chatbot/live_fallback_mixin.py

@@ -8,13 +8,12 @@ from pathlib import Path
 from typing import Any
 
 from ..source_metadata import classify_source_kind
+from .constants import DOC_SUFFIXES
 from .types import (
     ChunkRecord,
     RetrievedChunk,
 )
 
-DOC_SUFFIXES = {".md", ".mdx", ".txt", ".rst", ".adoc", ".ipynb"}
-
 
 class LiveFallbackMixin:
     """Mixin providing live-repo fallback search methods."""

{deepdoc-2.2.0 → deepdoc-2.3.0}/deepdoc/chatbot/retrieval_mixin.py

@@ -7,6 +7,7 @@ from pathlib import Path
 import re
 from typing import Any
 
+from .constants import DOC_SUFFIXES, STOPWORD_TOKENS
 from .persistence import (
     query_lexical_index,
     similarity_search,
@@ -15,44 +16,6 @@ from .types import (
     RetrievedChunk,
 )
 
-STOPWORD_TOKENS = {
-    "a",
-    "an",
-    "and",
-    "any",
-    "are",
-    "can",
-    "does",
-    "first",
-    "for",
-    "from",
-    "handle",
-    "handled",
-    "how",
-    "in",
-    "is",
-    "it",
-    "its",
-    "of",
-    "or",
-    "repo",
-    "repository",
-    "show",
-    "that",
-    "the",
-    "this",
-    "to",
-    "use",
-    "what",
-    "went",
-    "where",
-    "who",
-    "which",
-    "with",
-    "work",
-}
-DOC_SUFFIXES = {".md", ".mdx", ".txt", ".rst", ".adoc", ".ipynb"}
-
 
 class RetrievalMixin:
     """Mixin providing retrieval and search methods for ChatbotQueryService."""

{deepdoc-2.2.0 → deepdoc-2.3.0}/deepdoc/chatbot/service.py

@@ -39,59 +39,18 @@ from .types import (
     SourceCatalogEntry,
 )
 
-from .retrieval_mixin import RetrievalMixin
 from .answer_mixin import AnswerMixin
+from .constants import (
+    CODE_WORKSPACE_CONFIG_NAMES,
+    CODE_WORKSPACE_CONFIG_SUFFIXES,
+    CODE_WORKSPACE_SUFFIXES,
+    DOC_SUFFIXES,
+    STOPWORD_TOKENS,
+)
 from .live_fallback_mixin import LiveFallbackMixin
+from .retrieval_mixin import RetrievalMixin
 from .routes import create_fastapi_app, QueryRequest, DeepResearchRequest, CodeDeepRequest
 
-STOPWORD_TOKENS = {
-    "a",
-    "an",
-    "and",
-    "any",
-    "are",
-    "can",
-    "does",
-    "first",
-    "for",
-    "from",
-    "handle",
-    "handled",
-    "how",
-    "in",
-    "is",
-    "it",
-    "its",
-    "of",
-    "or",
-    "repo",
-    "repository",
-    "show",
-    "that",
-    "the",
-    "this",
-    "to",
-    "use",
-    "what",
-    "went",
-    "where",
-    "who",
-    "which",
-    "with",
-    "work",
-}
-DOC_SUFFIXES = {".md", ".mdx", ".txt", ".rst", ".adoc", ".ipynb"}
-CODE_WORKSPACE_SUFFIXES = {
-    ".py", ".js", ".jsx", ".ts", ".tsx", ".go", ".php", ".java", ".rb",
-    ".rs", ".vue", ".svelte", ".html", ".css", ".scss", ".sass",
-}
-CODE_WORKSPACE_CONFIG_NAMES = {
-    ".env", ".env.example", "docker-compose.yml", "docker-compose.yaml",
-    "package.json", "pyproject.toml", "requirements.txt", "composer.json",
-    "go.mod", "cargo.toml", "gemfile",
-}
-CODE_WORKSPACE_CONFIG_SUFFIXES = {".json", ".toml", ".yaml", ".yml", ".ini", ".cfg"}
-
 
 class ChatbotQueryService(RetrievalMixin, AnswerMixin, LiveFallbackMixin):
     """Query all chatbot corpora and answer with grounded citations."""

{deepdoc-2.2.0 → deepdoc-2.3.0}/deepdoc/chatbot/settings.py

@@ -2,13 +2,14 @@
 
 from __future__ import annotations
 
-from copy import deepcopy
 import os
 from pathlib import Path
 from typing import Any
 from urllib.parse import urlparse
 import zlib
 
+from ..config import _deep_merge
+
 DEFAULT_CHATBOT_CONFIG: dict[str, Any] = {
     "enabled": False,
     "index_dir": ".deepdoc/chatbot",
@@ -113,16 +114,6 @@ DEFAULT_CHATBOT_CONFIG: dict[str, Any] = {
 }
 
 
-def _deep_merge(base: dict[str, Any], override: dict[str, Any]) -> dict[str, Any]:
-    merged = deepcopy(base)
-    for key, value in override.items():
-        if isinstance(value, dict) and isinstance(merged.get(key), dict):
-            merged[key] = _deep_merge(merged[key], value)
-        else:
-            merged[key] = value
-    return merged
-
-
 def get_chatbot_cfg(cfg: dict[str, Any]) -> dict[str, Any]:
     return _deep_merge(DEFAULT_CHATBOT_CONFIG, cfg.get("chatbot", {}))
 

{deepdoc-2.2.0 → deepdoc-2.3.0}/deepdoc/cli.py

@@ -200,8 +200,10 @@ def init(name, description, provider, model, output_dir, with_chatbot):
         "openai": ("gpt-4o", "OPENAI_API_KEY"),
         "ollama": ("ollama/llama3.2", None),
         "azure": ("azure/gpt-4o", "AZURE_API_KEY"),
+        "google": ("gemini/gemini-1.5-pro", "GEMINI_API_KEY"),
+        "gemini": ("gemini/gemini-1.5-pro", "GEMINI_API_KEY"),
     }
-    default_model, default_key_env = provider_defaults.get(provider, ("", ""))
+    default_model, default_key_env = provider_defaults.get(provider, ("", "DEEPDOC_LLM_API_KEY"))
     resolved_model = model or default_model
 
     cfg = dict(DEFAULT_CONFIG)
@@ -261,14 +263,15 @@ def init(name, description, provider, model, output_dir, with_chatbot):
         )
         next_steps.append("  4. Generate docs:     [bold]deepdoc generate[/bold]")
         next_steps.append("  5. Preview locally:   [bold]deepdoc serve[/bold]")
-    elif cfg["llm"]["api_key_env"]:
-        next_steps.append(
-            f"  2. Set your API key:  [bold]export {cfg['llm']['api_key_env']}=...[/bold]"
-        )
+    elif provider == "ollama":
+        next_steps.append("  2. Make sure Ollama is running locally")
         next_steps.append("  3. Generate docs:     [bold]deepdoc generate[/bold]")
         next_steps.append("  4. Preview locally:   [bold]deepdoc serve[/bold]")
     else:
-        next_steps.append("  2. Make sure Ollama is running locally")
+        key_env = cfg["llm"].get("api_key_env") or "DEEPDOC_LLM_API_KEY"
+        next_steps.append(
+            f"  2. Set your API key:  [bold]export {key_env}=...[/bold]"
+        )
         next_steps.append("  3. Generate docs:     [bold]deepdoc generate[/bold]")
         next_steps.append("  4. Preview locally:   [bold]deepdoc serve[/bold]")
     if with_chatbot:
@@ -1320,7 +1323,7 @@ def _detect_generated_deepdoc_version(repo_root: Path, output_dir: Path) -> str
     for directory in candidates:
         if not directory.exists():
             continue
-        for doc_path in sorted(directory.rglob("*.mdx")):
+        for doc_path in sorted(directory.rglob("*.md")):
             try:
                 content = doc_path.read_text(encoding="utf-8", errors="replace")
             except OSError:
@@ -1456,7 +1459,7 @@ def _deployment_quality_blockers(repo_root: Path, output_dir: Path) -> list[str]
     if output_dir.exists():
         invalid_pages: list[str] = []
         stub_pages: list[str] = []
-        for doc_path in sorted(output_dir.rglob("*.mdx")):
+        for doc_path in sorted(output_dir.rglob("*.md")):
             try:
                 content = doc_path.read_text(encoding="utf-8")
             except Exception:

{deepdoc-2.2.0 → deepdoc-2.3.0}/deepdoc/generator/__init__.py

@@ -6,28 +6,16 @@ from .generation import (
     summarize_generation_results,
     BucketGenerationEngine,
 )
-from .mdx_compile_gate import GateOutcome, apply_mdx_compile_gate
-from .mdx_validator import (
-    MdxCompileError,
-    ValidationOutcome,
-    bootstrap_validator,
-    ensure_node_available,
-    validate_mdx,
-)
 from .validation import ValidationResult, PageValidator
 from .post_processors import (
     _fix_mermaid_diagram,
     build_internal_doc_link_maps,
-    escape_mdx_route_params,
-    escape_mdx_text_hazards,
     fix_file_references,
     fix_mermaid_diagrams,
     normalize_code_fence_languages,
     normalize_explanatory_lines_outside_fences,
     normalize_html_code_blocks,
-    normalize_mdx_steps,
     repair_internal_doc_links,
-    repair_mdx_component_blocks,
     repair_split_object_code_fences,
     repair_dangling_plain_fences,
     repair_unbalanced_code_fences,

{deepdoc-2.2.0 → deepdoc-2.3.0}/deepdoc/generator/evidence.py

@@ -34,12 +34,17 @@ from ..llm import LLMClient
 from ..parser import parse_file, supported_extensions
 from ..parser.base import ParsedFile, Symbol
 from ..planner import DocBucket, DocPlan, RepoScan, tracked_bucket_files
-from ..prompts_v2 import SYSTEM_V2, get_prompt_for_bucket
+from ..prompts import SYSTEM_V2, get_prompt_for_bucket
 from ..scanner import _classify_file_role
 from ..openapi import parse_openapi_spec, spec_to_context_string
 
 console = Console()
 
+_EP_TITLE_RE = re.compile(
+    r"^(GET|POST|PUT|PATCH|DELETE|HEAD|OPTIONS|CONNECT|TRACE)\s+(/\S*)",
+    re.IGNORECASE,
+)
+
 # ═════════════════════════════════════════════════════════════════════════════
 # 3.1  Evidence Assembly
 # ═════════════════════════════════════════════════════════════════════════════
@@ -67,6 +72,7 @@ class AssembledEvidence:
     compressed_cards_context: str = ""
     files_included_raw: int = 0
     files_compressed: int = 0
+    compressed_file_paths: set[str] = field(default_factory=set)
     coverage_files_total: int = 0
     helper_context: str = ""  # resolved helper/utility function bodies
     flow_context: str = ""  # call graph + flow evidence (entrypoints, chains, side effects)
@@ -141,7 +147,7 @@ class EvidenceAssembler:
             source_ctx,
             compressed_cards_ctx,
             files_included_raw,
-            files_compressed,
+            compressed_file_paths,
             coverage_total,
         ) = self._build_source_context(bucket)
         endpoints_detail = self._build_endpoints_detail(bucket)
@@ -204,7 +210,8 @@ class EvidenceAssembler:
             flow_context=flow_ctx,
             total_evidence_chars=total,
             files_included_raw=files_included_raw,
-            files_compressed=files_compressed,
+            files_compressed=len(compressed_file_paths),
+            compressed_file_paths=compressed_file_paths,
             coverage_files_total=coverage_total,
             evidence_file_paths=evidence_files,
             config_env_context=config_env_ctx,
@@ -316,11 +323,12 @@ class EvidenceAssembler:
             included += 1
 
         cards_context = self._format_compressed_cards(compressed_cards)
+        compressed_paths = {card.file_path for card in compressed_cards}
         return (
             "\n".join(parts),
             cards_context,
             included,
-            len(compressed_cards),
+            compressed_paths,
             len(ranked_files),
         )
 
@@ -780,7 +788,7 @@ class EvidenceAssembler:
         """Extract actual env var names from source files for grounded config docs."""
         env_vars: dict[str, list[str]] = {}  # var_name -> [file_paths]
 
-        for src_file in bucket.owned_files:
+        for src_file in list(bucket.owned_files) + list(bucket.artifact_refs or []):
             src_path = self.repo_root / src_file
             if not src_path.exists():
                 continue
@@ -1052,10 +1060,11 @@ class EvidenceAssembler:
 
         # ── endpoint_ref: match specific endpoint, pull deep evidence ─────
         if hints.get("is_endpoint_ref"):
-            # The title is e.g. "GET /api/v1/orders" — extract method+path
-            title_parts = bucket.title.split(" ", 1)
-            ref_method = title_parts[0].upper() if len(title_parts) >= 1 else ""
-            ref_path = title_parts[1] if len(title_parts) >= 2 else ""
+            # Extract METHOD /path from title via regex — more robust than split(" ", 1)
+            # since titles may not always follow the "GET /path" convention.
+            _m = _EP_TITLE_RE.match(bucket.title)
+            ref_method = _m.group(1).upper() if _m else ""
+            ref_path = _m.group(2) if _m else ""
 
             # Find matching bundle via handler symbol or method+path
             matched_bundle = None