docs: output generated sources under docs/lib and docs/mcp

docforge/cli/commands.py

@@ -39,7 +39,7 @@ def cli() -> None:
 @click.option(
     "--docs-dir",
     type=click.Path(path_type=Path),
-    default=Path("docs"),
+    default=Path("docs/lib"),
     help="Directory for MD sources",
 )
 @click.option(
@@ -61,7 +61,7 @@ def cli() -> None:
 @click.option(
     "--out-dir",
     type=click.Path(path_type=Path),
-    default=Path("mcp_docs"),
+    default=Path("docs/mcp"),
     help="MCP output directory",
 )
 def build(
@@ -144,6 +144,7 @@ def build(
             docs_dir,
             project_name,
             module_is_source,
+            readme_dir=mkdocs_yml.parent,
         )
 
         click.echo(f"Generating MkDocs config {mkdocs_yml}...")
@@ -177,7 +178,7 @@ def build(
 @click.option(
     "--out-dir",
     type=click.Path(path_type=Path),
-    default=Path("mcp_docs"),
+    default=Path("docs/mcp"),
     help="MCP root directory",
 )
 def serve(

docforge/cli/mcp_utils.py

@@ -63,7 +63,7 @@ def serve(module: str, mcp_root: Path) -> None:
             If the MCP documentation bundle is missing required files or directories.
     """
     if not mcp_root.exists():
-        raise click.ClickException(f"mcp_docs directory not found: {mcp_root}")
+        raise click.ClickException(f"MCP docs directory not found: {mcp_root}")
 
     required = [
         mcp_root / "index.json",

docforge/cli/mkdocs_utils.py

@@ -4,6 +4,7 @@
 Utilities for working with MkDocs in the doc-forge CLI.
 """
 
+import os
 from importlib import resources
 from pathlib import Path
 
@@ -20,6 +21,7 @@ def generate_sources(
     docs_dir: Path,
     project_name: str | None = None,
     module_is_source: bool | None = None,
+    readme_dir: Path | None = None,
 ) -> None:
     """
     Generate MkDocs Markdown sources for a Python module.
@@ -42,6 +44,10 @@ def generate_sources(
         module_is_source (Optional[bool]):
             If True, treat the specified module directory as the project root
             rather than a nested module.
+
+        readme_dir (Optional[Path]):
+            Directory where the generated README.md should be written. If not
+            provided, defaults to the parent of ``docs_dir``.
     """
     loader = GriffeLoader()
     discovered_paths = discover_module_paths(module)
@@ -58,6 +64,7 @@ def generate_sources(
         project,
         docs_dir,
         module_is_source,
+        readme_dir,
     )
 
 
@@ -117,6 +124,7 @@ def generate_config(
         data = yaml.safe_load(text)
 
     data["site_name"] = site_name
+    data["docs_dir"] = Path(os.path.relpath(docs_dir, out.parent)).as_posix()
     data["nav"] = nav_block
 
     out.write_text(yaml.safe_dump(data, sort_keys=False), encoding="utf-8")