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

docforge/cli/commands.py

@@ -44,6 +44,11 @@ def cli() -> None:
 @click.option(
     "--wiki", is_flag=True, help="Build a hand-written wiki as its own MkDocs site"
 )
+@click.option(
+    "--refresh",
+    is_flag=True,
+    help="Regenerate existing docs/mkdocs.{kind}.yml configs from templates",
+)
 @click.option(
     "--module-is-source",
     is_flag=True,
@@ -90,6 +95,7 @@ def build(
     mkdocs: bool,
     api: bool,
     wiki: bool,
+    refresh: bool,
     module_is_source: bool,
     module: str | None,
     openapi_spec: Path | None,
@@ -123,6 +129,9 @@ def build(
           provided.
         - `--mkdocs`, `--api`, and `--wiki` emit independent MkDocs builds,
           while `--mcp` emits a machine-readable bundle.
+        - Configuration files are generated only when absent; an existing
+          `docs/mkdocs.{kind}.yml` is used as-is. Pass `--refresh` to
+          rebaseline it from the templates.
 
     Args:
         mcp (bool):
@@ -137,6 +146,10 @@ def build(
         wiki (bool):
             Build a hand-written wiki directory as its own MkDocs site.
 
+        refresh (bool):
+            Regenerate ``docs/mkdocs.{kind}.yml`` from templates even when
+            it already exists. By default, existing configs are used as-is.
+
         module_is_source (bool):
             Treat the specified module directory as the project root.
 
@@ -221,6 +234,14 @@ def build(
 
         config_paths: list[Path] = []
         for kind in kinds:
+            out = docs_dir / f"mkdocs.{kind}.yml"
+            if out.exists() and not refresh:
+                click.echo(
+                    f"Using existing MkDocs config {out} (run --refresh to rebaseline)..."
+                )
+                config_paths.append(out)
+                continue
+
             kind_root = wiki_dir if kind == "wiki" else docs_dir / kind
 
             site_name_kind = site_name or module or Path.cwd().name
@@ -238,7 +259,6 @@ def build(
             else:
                 nav_block = [{"API Reference": "index.md"}]
 
-            out = docs_dir / f"mkdocs.{kind}.yml"
             click.echo(f"Generating MkDocs config {out}...")
             mkdocs_utils.generate_site_config(
                 kind,