feat: use file-wins mkdocs configs with --refresh; wiki template in mongo-ops style

tests/cli/test_build_mkdocs.py

@@ -90,3 +90,73 @@ def test_mkdocs_build_without_site_name_uses_module_as_default_full_flow(
 
         # Docs must be generated under the nested docs/lib dir
         assert (cwd / "docs" / "lib" / "testpkg" / "mod.md").exists()
+
+
+def test_existing_lib_config_used_verbatim_without_refresh(
+    cli_runner,
+    mock_mkdocs_build,
+    mock_mkdocs_load_config,
+):
+    with cli_runner.isolated_filesystem():
+        cwd = Path.cwd()
+        pkg = cwd / "testpkg"
+        pkg.mkdir()
+        (pkg / "__init__.py").write_text("")
+        (pkg / "mod.py").write_text("def f(): ...\n")
+
+        nav_file = cwd / "docforge.nav.yml"
+        nav_file.write_text(
+            "home: lib/testpkg/index.md\ngroups: {}\n",
+            encoding="utf-8",
+        )
+
+        config = cwd / "docs" / "mkdocs.lib.yml"
+        config.parent.mkdir(parents=True)
+        sentinel = "site_name: Custom Lib\nnav: []\n"
+        config.write_text(sentinel, encoding="utf-8")
+
+        result = cli_runner.invoke(
+            cli,
+            ["build", "--mkdocs", "--module", "testpkg"],
+        )
+
+        assert result.exit_code == 0, result.output
+        assert mock_mkdocs_build() is True
+        assert config.read_text(encoding="utf-8") == sentinel
+        assert "Using existing MkDocs config" in result.output
+
+
+def test_refresh_rebases_existing_lib_config(
+    cli_runner,
+    mock_mkdocs_build,
+    mock_mkdocs_load_config,
+):
+    with cli_runner.isolated_filesystem():
+        cwd = Path.cwd()
+        pkg = cwd / "testpkg"
+        pkg.mkdir()
+        (pkg / "__init__.py").write_text("")
+        (pkg / "mod.py").write_text("def f(): ...\n")
+
+        nav_file = cwd / "docforge.nav.yml"
+        nav_file.write_text(
+            "home: lib/testpkg/index.md\ngroups: {}\n",
+            encoding="utf-8",
+        )
+
+        config = cwd / "docs" / "mkdocs.lib.yml"
+        config.parent.mkdir(parents=True)
+        config.write_text("site_name: Stale\nnav: []\n", encoding="utf-8")
+
+        result = cli_runner.invoke(
+            cli,
+            ["build", "--mkdocs", "--module", "testpkg", "--refresh"],
+        )
+
+        assert result.exit_code == 0, result.output
+        assert mock_mkdocs_build() is True
+        content = config.read_text(encoding="utf-8")
+        assert "site_name: testpkg" in content
+        assert "docs_dir: lib" in content
+        assert "site_dir: ../site/lib" in content
+        assert "Home: testpkg/index.md" in content

tests/cli/test_build_wiki.py

@@ -111,6 +111,33 @@ def test_wiki_without_module_flag_ok(
         assert mock_mkdocs_build() is True
 
 
+def test_wiki_existing_config_used_verbatim_without_refresh(
+    cli_runner,
+    mock_mkdocs_build,
+    mock_mkdocs_load_config,
+):
+    with cli_runner.isolated_filesystem():
+        cwd = Path.cwd()
+
+        wiki = cwd / "docs" / "wiki"
+        wiki.mkdir(parents=True)
+        (wiki / "index.md").write_text("# Home", encoding="utf-8")
+
+        config = cwd / "docs" / "mkdocs.wiki.yml"
+        sentinel = "site_name: Custom Wiki\nnav: []\n"
+        config.write_text(sentinel, encoding="utf-8")
+
+        result = cli_runner.invoke(
+            cli,
+            ["build", "--wiki", "--site-name", "Wiki Site"],
+        )
+
+        assert result.exit_code == 0, result.output
+        assert mock_mkdocs_build() is True
+        assert config.read_text(encoding="utf-8") == sentinel
+        assert "Using existing MkDocs config" in result.output
+
+
 def test_missing_wiki_dir_errors(cli_runner, mock_mkdocs_build):
     with cli_runner.isolated_filesystem():
         cwd = Path.cwd()