deepdoc 2.0.0__tar.gz → 2.1.0__tar.gz

{deepdoc-2.0.0 → deepdoc-2.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: deepdoc
-Version: 2.0.0
+Version: 2.1.0
 Summary: Auto-generate beautiful docs from any codebase
 Author: Pranav Kumar
 License: MIT
@@ -406,13 +406,13 @@ deepdoc update --deploy           # Update + deploy
 1. Loads the saved sync baseline, plan, and generation ledger from `.deepdoc/`.
 2. Diffs committed changes from the last synced commit to the current `HEAD`.
 3. Chooses a strategy automatically:
-   - incremental update
-   - targeted replan
-   - full replan
+   - **incremental** — regenerate only the stale bucket pages
+   - **targeted replan** — new/deleted files or endpoint structure changes; re-plans affected buckets then regenerates them. Full replan is never triggered automatically for normal code changes.
 4. Compares the saved scan cache with the current scan so semantic endpoint changes can refresh impacted docs even when ownership files do not line up directly.
-5. Regenerates only the affected bucket pages when safe.
-6. Incrementally refreshes the chatbot corpora from the same update run.
-7. Rebuilds site config and nav afterward.
+5. Regenerates only the affected bucket pages. Deleted files are cleaned up in-place: orphaned buckets and their MDX pages are removed, partially-emptied buckets are marked stale and regenerated.
+6. Appends an entry to `.deepdoc/changelog.json` and regenerates `docs/whats-changed.mdx` so the docs site always shows a current commit-by-commit change log.
+7. Incrementally refreshes the chatbot corpora from the same update run.
+8. Rebuilds site config and nav afterward.
 
 If git is unavailable, it falls back to hash-based staleness detection for recovery.
 
@@ -421,7 +421,7 @@ Generation writes quality artifacts under `.deepdoc/`:
 - `.deepdoc/generation_quality.json` records invalid/degraded pages, coverage metrics, local setup warnings, and consistency summary data.
 - `.deepdoc/consistency_warnings.json` records warning-only cross-page identifier consistency findings.
 
-Generated MDX pages include provenance frontmatter such as `deepdoc_generated_commit`, `deepdoc_generated_at`, `deepdoc_generated_version`, `deepdoc_status`, and `deepdoc_evidence_files`. The generated Fumadocs site renders a subtle "Last generated from commit ..." badge when this metadata is present.
+Generated MDX pages include provenance frontmatter such as `deepdoc_generated_commit`, `deepdoc_generated_at`, `deepdoc_generated_version`, `deepdoc_status`, `deepdoc_evidence_files`, and `deepdoc_prereqs` (prerequisite page slugs). The generated Fumadocs site renders a subtle "Last generated from commit ..." badge and wires prev/next navigation arrows automatically. Pages with prerequisites show a "Read first:" callout at the top.
 
 **Options:**
 
@@ -740,9 +740,7 @@ site:
 | `site.favicon` | `""` | Path to favicon |
 | `site.logo` | `""` | Path to logo |
 | **Compatibility** | | |
-| `compatibility.deprecated_version_warning.enabled` | `true` | Warn when existing generated docs were produced by a deprecated DeepDoc version |
-| `compatibility.deprecated_version_warning.minimum_version` | `1.0.0` | Minimum generated DeepDoc version before an upgrade warning appears |
-| `compatibility.deprecated_version_warning.upgrade_command` | `python3 -m pip install --upgrade deepdoc` | Command shown in the upgrade warning |
+| `compatibility.deprecated_version_warning.enabled` | `true` | Warn when existing generated docs were produced by a different major version of DeepDoc (e.g. docs from v1.x with CLI v2.x). Suppressed for minor/patch version gaps. |
 
 ---
 

{deepdoc-2.0.0 → deepdoc-2.1.0}/README.md

@@ -367,13 +367,13 @@ deepdoc update --deploy           # Update + deploy
 1. Loads the saved sync baseline, plan, and generation ledger from `.deepdoc/`.
 2. Diffs committed changes from the last synced commit to the current `HEAD`.
 3. Chooses a strategy automatically:
-   - incremental update
-   - targeted replan
-   - full replan
+   - **incremental** — regenerate only the stale bucket pages
+   - **targeted replan** — new/deleted files or endpoint structure changes; re-plans affected buckets then regenerates them. Full replan is never triggered automatically for normal code changes.
 4. Compares the saved scan cache with the current scan so semantic endpoint changes can refresh impacted docs even when ownership files do not line up directly.
-5. Regenerates only the affected bucket pages when safe.
-6. Incrementally refreshes the chatbot corpora from the same update run.
-7. Rebuilds site config and nav afterward.
+5. Regenerates only the affected bucket pages. Deleted files are cleaned up in-place: orphaned buckets and their MDX pages are removed, partially-emptied buckets are marked stale and regenerated.
+6. Appends an entry to `.deepdoc/changelog.json` and regenerates `docs/whats-changed.mdx` so the docs site always shows a current commit-by-commit change log.
+7. Incrementally refreshes the chatbot corpora from the same update run.
+8. Rebuilds site config and nav afterward.
 
 If git is unavailable, it falls back to hash-based staleness detection for recovery.
 
@@ -382,7 +382,7 @@ Generation writes quality artifacts under `.deepdoc/`:
 - `.deepdoc/generation_quality.json` records invalid/degraded pages, coverage metrics, local setup warnings, and consistency summary data.
 - `.deepdoc/consistency_warnings.json` records warning-only cross-page identifier consistency findings.
 
-Generated MDX pages include provenance frontmatter such as `deepdoc_generated_commit`, `deepdoc_generated_at`, `deepdoc_generated_version`, `deepdoc_status`, and `deepdoc_evidence_files`. The generated Fumadocs site renders a subtle "Last generated from commit ..." badge when this metadata is present.
+Generated MDX pages include provenance frontmatter such as `deepdoc_generated_commit`, `deepdoc_generated_at`, `deepdoc_generated_version`, `deepdoc_status`, `deepdoc_evidence_files`, and `deepdoc_prereqs` (prerequisite page slugs). The generated Fumadocs site renders a subtle "Last generated from commit ..." badge and wires prev/next navigation arrows automatically. Pages with prerequisites show a "Read first:" callout at the top.
 
 **Options:**
 
@@ -701,9 +701,7 @@ site:
 | `site.favicon` | `""` | Path to favicon |
 | `site.logo` | `""` | Path to logo |
 | **Compatibility** | | |
-| `compatibility.deprecated_version_warning.enabled` | `true` | Warn when existing generated docs were produced by a deprecated DeepDoc version |
-| `compatibility.deprecated_version_warning.minimum_version` | `1.0.0` | Minimum generated DeepDoc version before an upgrade warning appears |
-| `compatibility.deprecated_version_warning.upgrade_command` | `python3 -m pip install --upgrade deepdoc` | Command shown in the upgrade warning |
+| `compatibility.deprecated_version_warning.enabled` | `true` | Warn when existing generated docs were produced by a different major version of DeepDoc (e.g. docs from v1.x with CLI v2.x). Suppressed for minor/patch version gaps. |
 
 ---
 

{deepdoc-2.0.0 → deepdoc-2.1.0}/deepdoc/__init__.py

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

deepdoc-2.1.0/deepdoc/changelog_writer.py

@@ -0,0 +1,161 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from .persistence_v2 import append_changelog_entry, load_changelog, load_plan, save_plan
+
+_STRATEGY_LABEL = {
+    "incremental": "Incremental update",
+    "targeted_replan": "Targeted replan",
+    "full_replan": "Full replan",
+    "full_generate": "Full generation",
+}
+
+
+def record_and_write(
+    repo_root: Path,
+    output_dir: Path,
+    *,
+    commit: str,
+    commit_message: str,
+    commit_date: str,
+    strategy: str,
+    pages_updated: list[str],
+    files_changed: list[str],
+    is_initial: bool = False,
+) -> None:
+    """Append one changelog entry and regenerate whats-changed.mdx."""
+    entry = {
+        "commit": commit[:8],
+        "date": commit_date,
+        "commit_message": commit_message,
+        "strategy": strategy,
+        "pages_updated": pages_updated,
+        "files_changed": files_changed[:20],
+        "is_initial": is_initial,
+    }
+    append_changelog_entry(repo_root, entry)
+    write_whats_changed_page(repo_root, output_dir)
+
+
+def write_whats_changed_page(repo_root: Path, output_dir: Path) -> None:
+    """Write docs/whats-changed.mdx from .deepdoc/changelog.json."""
+    entries = load_changelog(repo_root)
+    mdx = _build_mdx(entries)
+    output_dir.mkdir(parents=True, exist_ok=True)
+    (output_dir / "whats-changed.mdx").write_text(mdx, encoding="utf-8")
+    _ensure_in_nav(repo_root)
+
+
+def _build_mdx(entries: list[dict]) -> str:
+    lines = [
+        "---",
+        'title: "What\'s Changed"',
+        'description: "A commit-by-commit log of every documentation update — which pages changed, which source files triggered the change, and how the update was handled."',
+        "---",
+        "",
+        "# What's Changed",
+        "",
+        "Every time you run `deepdoc generate` or `deepdoc update`, this page is regenerated automatically.",
+        "Each entry shows the commit that triggered the run, the strategy DeepDoc chose, the pages that were",
+        "updated, and the source files that caused the change.",
+        "",
+    ]
+
+    if not entries:
+        lines.append(
+            "<Callout>No changelog entries yet. Run `deepdoc generate` to create the first entry.</Callout>"
+        )
+        return "\n".join(lines)
+
+    lines.append("<Accordions>")
+    for entry in entries:
+        date = entry.get("date", "")
+        msg = entry.get("commit_message", "update")
+        sha = entry.get("commit", "")
+        pages = entry.get("pages_updated", [])
+        files = entry.get("files_changed", [])
+        strategy = entry.get("strategy", "")
+        is_initial = entry.get("is_initial", False)
+        strategy_label = _STRATEGY_LABEL.get(strategy, strategy)
+
+        title = f"{date} — {msg[:72]} ({sha})"
+        lines.append(f'<Accordion title="{title}">')
+        lines.append("")
+
+        # Commit metadata row
+        lines.append("| | |")
+        lines.append("|---|---|")
+        lines.append(f"| **Commit** | `{sha}` |")
+        lines.append(f"| **Date** | {date} |")
+        lines.append(f"| **Strategy** | {strategy_label} |")
+        lines.append(f"| **Message** | {msg} |")
+        lines.append("")
+
+        if is_initial:
+            lines.append(
+                f"**Initial generation** — {len(pages)} page(s) created from scratch."
+            )
+            if pages:
+                lines.append("")
+                lines.append("**Pages generated:**")
+                lines.append("")
+                for s in pages:
+                    lines.append(f"- [{_slug_to_title(s)}](/{s})")
+        else:
+            # Pages updated
+            if pages:
+                lines.append(f"**{len(pages)} page(s) updated:**")
+                lines.append("")
+                for s in pages:
+                    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>"
+                )
+
+            # Source files that changed
+            if files:
+                lines.append("")
+                lines.append(f"**Source files that triggered this update ({len(files)}):**")
+                lines.append("")
+                for f in files[:20]:
+                    lines.append(f"- `{f}`")
+                if len(files) > 20:
+                    lines.append(f"- *...and {len(files) - 20} more*")
+
+            # What the strategy means
+            lines.append("")
+            if strategy == "incremental":
+                lines.append(
+                    "> **Incremental update** — only the pages whose source files changed were regenerated. All other pages were left untouched."
+                )
+            elif strategy == "targeted_replan":
+                lines.append(
+                    "> **Targeted replan** — new or deleted files were detected. DeepDoc re-evaluated which buckets own those files, updated the plan, and regenerated affected pages."
+                )
+            elif strategy == "full_replan":
+                lines.append(
+                    "> **Full replan** — the engine schema changed or a force-replan was requested. All buckets were re-planned and regenerated."
+                )
+
+        lines.append("")
+        lines.append("</Accordion>")
+
+    lines.append("</Accordions>")
+    return "\n".join(lines)
+
+
+def _slug_to_title(slug: str) -> str:
+    return slug.replace("-", " ").title()
+
+
+def _ensure_in_nav(repo_root: Path) -> None:
+    """Add whats-changed to Start Here section of the saved plan if not already there."""
+    plan = load_plan(repo_root)
+    if plan is None or not hasattr(plan, "nav_structure"):
+        return
+    section = plan.nav_structure.setdefault("Start Here", [])
+    if "whats-changed" not in section:
+        section.append("whats-changed")
+    save_plan(plan, repo_root)

{deepdoc-2.0.0 → deepdoc-2.1.0}/deepdoc/chatbot/answer_mixin.py

@@ -570,13 +570,14 @@ class AnswerMixin:
                 reason="mentioned_source",
             )
 
-        by_path: dict[str, dict[str, Any]] = {}
+        seen_ranges: set[tuple[str, int, int]] = set()
+        result: list[dict[str, Any]] = []
         for row in rows:
-            path = row["file_path"]
-            existing = by_path.get(path)
-            if not existing or float(row.get("score", 0.0)) > float(existing.get("score", 0.0)):
-                by_path[path] = row
-        return list(by_path.values())[:8]
+            key = (row["file_path"], row.get("start_line", 0), row.get("end_line", 0))
+            if key not in seen_ranges:
+                seen_ranges.add(key)
+                result.append(row)
+        return result[:8]
 
     def _apply_evidence_contract(
         self,
@@ -774,6 +775,7 @@ class AnswerMixin:
         for text in texts:
             for raw_path, raw_start, raw_end in pattern.findall(str(text or "")):
                 path = raw_path.strip("`'\".,:;()[]{}")
+                path = re.sub(r"^\./", "", path)
                 if self._is_reference_doc_path(path):
                     continue
                 if not self._is_code_workspace_path(path, allow_config=True):

{deepdoc-2.0.0 → deepdoc-2.1.0}/deepdoc/chatbot/persistence.py

@@ -440,7 +440,7 @@ def similarity_search(
             return [
                 RetrievedChunk(record=records[idx], score=float(score))
                 for score, idx in zip(scores[0], order[0], strict=False)
-                if idx >= 0 and idx < len(records)
+                if idx >= 0 and idx < len(records) and score > -0.5
             ]
         except Exception:
             pass

{deepdoc-2.0.0 → deepdoc-2.1.0}/deepdoc/chatbot/providers.py

@@ -185,7 +185,82 @@ class LiteLLMEmbeddingClient:
 
 
 def build_chat_client(cfg: dict[str, Any]) -> LiteLLMChatClient:
-    return LiteLLMChatClient(get_chatbot_cfg(cfg).get("answer", {}))
+    answer_cfg = get_chatbot_cfg(cfg).get("answer", {})
+    provider = (answer_cfg.get("provider") or "").strip()
+    model = (answer_cfg.get("model") or "").strip()
+
+    # If chatbot.answer is not explicitly configured, inherit from the doc-gen llm.* config.
+    # This means a single deepdoc init --provider X covers both doc generation and chatbot.
+    if not provider or not model:
+        llm_cfg = cfg.get("llm", {})
+        llm_provider = (llm_cfg.get("provider") or "").strip()
+        llm_model = (llm_cfg.get("model") or "").strip()
+        if llm_provider and llm_model:
+            answer_cfg = {
+                **answer_cfg,
+                "provider": llm_provider,
+                "model": llm_model,
+                "api_key_env": llm_cfg.get("api_key_env") or answer_cfg.get("api_key_env", ""),
+                "base_url": llm_cfg.get("base_url") or answer_cfg.get("base_url", ""),
+                "api_version": llm_cfg.get("api_version") or answer_cfg.get("api_version", ""),
+            }
+            provider, model = llm_provider, llm_model
+
+    if not provider or not model:
+        raise ValueError(
+            "\n\n"
+            "╔══════════════════════════════════════════════════════════════════════╗\n"
+            "║         CHATBOT NOT CONFIGURED — ACTION REQUIRED                    ║\n"
+            "╠══════════════════════════════════════════════════════════════════════╣\n"
+            "║                                                                      ║\n"
+            "║  No LLM is configured for the chatbot.                               ║\n"
+            "║                                                                      ║\n"
+            "║  OPTION 1 — reuse your doc-gen LLM (zero extra config):              ║\n"
+            "║    Just make sure llm.provider and llm.model are set.                ║\n"
+            "║    The chatbot will automatically use the same provider and key.      ║\n"
+            "║                                                                      ║\n"
+            "║  OPTION 2 — use a separate (e.g. cheaper) model for chat:            ║\n"
+            "║                                                                      ║\n"
+            "║    chatbot:                                                           ║\n"
+            "║      answer:                                                          ║\n"
+            "║        provider: <your-provider>    # openai, anthropic, azure, etc. ║\n"
+            "║        model: <your-model>          # matching model name            ║\n"
+            "║        api_key_env: <YOUR_KEY_ENV>  # env var holding your key       ║\n"
+            "║                                                                      ║\n"
+            "║  Any LiteLLM-compatible provider works:                              ║\n"
+            "║    https://docs.litellm.ai/docs/providers                            ║\n"
+            "╚══════════════════════════════════════════════════════════════════════╝\n"
+        )
+    is_azure = provider.lower() == "azure" or model.lower().startswith("azure/")
+    if is_azure:
+        base_url = (answer_cfg.get("base_url") or "").strip()
+        api_version = (answer_cfg.get("api_version") or "").strip()
+        missing = []
+        if not base_url or base_url.startswith("https://<"):
+            missing.append("base_url  (your Azure OpenAI endpoint URL)")
+        if not api_version:
+            missing.append("api_version  (e.g. 2024-02-01)")
+        if missing:
+            items = "\n".join(f"║    • {item:<64}║" for item in missing)
+            raise ValueError(
+                "\n\n"
+                "╔══════════════════════════════════════════════════════════════════════╗\n"
+                "║         AZURE CHATBOT NOT FULLY CONFIGURED — ACTION REQUIRED        ║\n"
+                "╠══════════════════════════════════════════════════════════════════════╣\n"
+                "║                                                                      ║\n"
+                "║  Azure OpenAI requires additional settings that are missing:         ║\n"
+                "║                                                                      ║\n"
+                f"{items}\n"
+                "║                                                                      ║\n"
+                "║  Add them to .deepdoc.yaml under llm: or chatbot.answer:             ║\n"
+                "║                                                                      ║\n"
+                "║    llm:                                                               ║\n"
+                "║      base_url: https://<resource>.openai.azure.com                   ║\n"
+                "║      api_version: 2024-02-01                                         ║\n"
+                "╚══════════════════════════════════════════════════════════════════════╝\n"
+            )
+
+    return LiteLLMChatClient(answer_cfg)
 
 
 def build_embedding_client(
@@ -198,8 +273,36 @@ def build_embedding_client(
 
     if backend == "fastembed":
         return FastembedEmbeddingClient(embeddings_cfg)
-    else:
-        return LiteLLMEmbeddingClient(embeddings_cfg)
+
+    provider = (embeddings_cfg.get("provider") or "").strip()
+    model = (embeddings_cfg.get("model") or "").strip()
+    if not provider or not model:
+        raise ValueError(
+            "\n\n"
+            "╔══════════════════════════════════════════════════════════════════════╗\n"
+            "║         EMBEDDINGS NOT CONFIGURED — ACTION REQUIRED                 ║\n"
+            "╠══════════════════════════════════════════════════════════════════════╣\n"
+            "║                                                                      ║\n"
+            "║  chatbot.embeddings.backend is set to 'litellm' but               ║\n"
+            "║  chatbot.embeddings.provider and .model are not set.                ║\n"
+            "║                                                                      ║\n"
+            "║  Either switch to the local (no-API-key) backend:                   ║\n"
+            "║                                                                      ║\n"
+            "║    chatbot:                                                           ║\n"
+            "║      embeddings:                                                      ║\n"
+            "║        backend: fastembed    # runs locally, no key needed           ║\n"
+            "║                                                                      ║\n"
+            "║  Or configure a cloud embedding provider:                            ║\n"
+            "║                                                                      ║\n"
+            "║    chatbot:                                                           ║\n"
+            "║      embeddings:                                                      ║\n"
+            "║        backend: litellm                                               ║\n"
+            "║        provider: <your-provider>   # e.g. openai, azure              ║\n"
+            "║        model: <your-model>         # e.g. text-embedding-3-large     ║\n"
+            "║        api_key_env: <YOUR_KEY_ENV> # env var holding your key        ║\n"
+            "╚══════════════════════════════════════════════════════════════════════╝\n"
+        )
+    return LiteLLMEmbeddingClient(embeddings_cfg)
 
 
 class FastembedEmbeddingClient:
@@ -207,6 +310,8 @@ class FastembedEmbeddingClient:
 
     def __init__(self, service_cfg: dict[str, Any]) -> None:
         self.service_cfg = service_cfg
+        # Fallback model if not set in config — explicit choice, not a vendor endorsement.
+        # Full model list: https://qdrant.github.io/fastembed/examples/Supported_Models/
         self.model = service_cfg.get(
             "fastembed_model", "nomic-ai/nomic-embed-text-v1.5"
         )

{deepdoc-2.0.0 → deepdoc-2.1.0}/deepdoc/chatbot/retrieval_mixin.py

@@ -213,7 +213,7 @@ class RetrievalMixin:
             hits = [
                 RetrievedChunk(
                     record=by_chunk_id[chunk_id],
-                    score=max(1.0, self._lexical_score(by_chunk_id[chunk_id], query_signals)),
+                    score=self._lexical_score(by_chunk_id[chunk_id], query_signals),
                 )
                 for chunk_id in chunk_ids
                 if chunk_id in by_chunk_id

{deepdoc-2.0.0 → deepdoc-2.1.0}/deepdoc/chatbot/routes.py

@@ -8,7 +8,7 @@ import threading
 from pathlib import Path
 from typing import Any
 
-from pydantic import BaseModel, Field
+from pydantic import BaseModel, Field, field_validator
 
 from .settings import chatbot_allowed_origins
 
@@ -19,6 +19,13 @@ class QueryRequest(BaseModel):
     question: str
     history: list[dict[str, str]] = Field(default_factory=list)
 
+    @field_validator("question")
+    @classmethod
+    def question_not_empty(cls, v: str) -> str:
+        if not v or not v.strip():
+            raise ValueError("question must not be empty")
+        return v
+
 
 class DeepResearchRequest(QueryRequest):
     """Incoming deep-research payload."""
@@ -110,7 +117,11 @@ def create_fastapi_app(repo_root: Path, cfg: dict[str, Any]):
 
         def event_stream():
             while True:
-                item = tokens.get()
+                try:
+                    item = tokens.get(timeout=30)
+                except queue.Empty:
+                    yield "event: ping\ndata: {}\n\n"
+                    continue
                 if item is None:
                     break
                 event_name, payload = item
@@ -154,7 +165,11 @@ def create_fastapi_app(repo_root: Path, cfg: dict[str, Any]):
 
         def event_stream():
             while True:
-                item = tokens.get()
+                try:
+                    item = tokens.get(timeout=30)
+                except queue.Empty:
+                    yield "event: ping\ndata: {}\n\n"
+                    continue
                 if item is None:
                     break
                 event_name, payload = item
@@ -223,7 +238,11 @@ def create_fastapi_app(repo_root: Path, cfg: dict[str, Any]):
 
         def event_stream():
             while True:
-                item = events.get()
+                try:
+                    item = events.get(timeout=30)
+                except queue.Empty:
+                    yield "event: ping\ndata: {}\n\n"
+                    continue
                 if item is None:
                     break
                 event_name, payload = item

{deepdoc-2.0.0 → deepdoc-2.1.0}/deepdoc/chatbot/service.py

@@ -535,13 +535,6 @@ class ChatbotQueryService(RetrievalMixin, AnswerMixin, LiveFallbackMixin):
             trace_callback=emit,
         )
         response["trace"] = trace
-        response["file_inventory"] = self._collect_file_inventory(
-            question,
-            response,
-            result.all_sources,
-            retrieval_cfg,
-            trace,
-        )
         response["response_mode"] = "code_deep"
         response["research_mode"] = "code_deep"
         response = self._finalize_answer_response(question, response, mode="code_deep")

{deepdoc-2.0.0 → deepdoc-2.1.0}/deepdoc/chatbot/settings.py

@@ -20,8 +20,8 @@ DEFAULT_CHATBOT_CONFIG: dict[str, Any] = {
         ],
     },
     "answer": {
-        "provider": "azure",
-        "model": "azure/gpt-4o-mini",
+        "provider": "",  # must be set in .deepdoc.yaml — run: deepdoc init --with-chatbot
+        "model": "",
         "api_key_env": "DEEPDOC_CHAT_API_KEY",
         "base_url": "",
         "api_version": "",
@@ -31,11 +31,13 @@ DEFAULT_CHATBOT_CONFIG: dict[str, Any] = {
         "continuation_context_chars": 12000,
     },
     "embeddings": {
-        "backend": "litellm",  # default: use configured litellm model (text-embedding-3-small, Azure, etc.)
-        "fastembed_model": "nomic-ai/nomic-embed-text-v1.5",  # only use if backend="fastembed"; 8192-token context, 768-dim
+        "backend": "fastembed",  # local by default — no API key needed; set to "litellm" for cloud embeddings
+        # Local model — runs offline, no API key. Explicit choice; swap to any model from:
+        # https://qdrant.github.io/fastembed/examples/Supported_Models/
+        "fastembed_model": "nomic-ai/nomic-embed-text-v1.5",
         "fastembed_batch_size": 4,
-        "provider": "azure",
-        "model": "azure/text-embedding-3-large",
+        "provider": "",  # only required when backend="litellm"
+        "model": "",
         "api_key_env": "DEEPDOC_EMBED_API_KEY",
         "base_url": "",
         "api_version": "",