Flatten MkDocs output structure, enforce root index.md, and add --module-is-source to produce deployable standalone static documentation sites without nested path issues.

# Merge Request: Flatten MkDocs Structure + `--module-is-source` Support

## Summary

This MR introduces structural improvements to the MkDocs generation pipeline to:

1. Ensure a root `docs/index.md` always exists
2. Flatten documentation structure (remove `docs/<module>/` nesting by default)
3. Add support for `--module-is-source` to treat the module as the documentation root
4. Align navigation (`docforge.nav.yml`) with the new flat layout
5. Regenerate MCP artifacts to reflect updated signatures and docstrings

This resolves static hosting issues (e.g., Nginx 403 due to missing `site/index.html`) and makes each generated MkDocs site deployable as a standalone static website.

---

## Motivation

Previously, documentation was generated under:

```
docs/<module>/...
```

Which resulted in:

```
site/<module>/index.html
```

When deployed at `/libs/<project>/`, this caused:

* Missing `site/index.html`
* Nginx returning 403 for root access
* Inconsistent static hosting behavior

This MR corrects the architecture so each MkDocs build is a valid static site with a root entry point.

---

## Key Changes

### 1️⃣ Flattened Docs Structure

**Before**

```
docs/docforge/index.md
```

**After**

```
docs/index.md
```

All documentation paths were updated accordingly:

* `docs/docforge/cli/...` → `docs/cli/...`
* `docs/docforge/models/...` → `docs/models/...`
* `docs/docforge/renderers/...` → `docs/renderers/...`

Navigation updated to match the flat layout.

---

### 2️⃣ Root Index Enforcement

`MkDocsRenderer` now guarantees:

* `docs/index.md` is always created
* Parent `index.md` files are auto-generated if missing
* Parent indexes link to child modules (idempotent behavior)

This ensures:

```
site/index.html
```

Always exists after `mkdocs build`.

---

### 3️⃣ New CLI Flag: `--module-is-source`

Added option:

```
--module-is-source
```

Behavior:

* Treats the provided module as the documentation root
* Removes the top-level module folder from generated paths
* Prevents redundant nesting when the module corresponds to the source root

Updated components:

* `cli.commands.build`
* `mkdocs_utils.generate_sources`
* `MkDocsRenderer.generate_sources`
* Stub files (`.pyi`)
* MCP JSON artifacts

---

### 4️⃣ Navigation Spec Update

`docforge.nav.yml` updated:

**Before**

```yaml
home: docforge/index.md
```

**After**

```yaml
home: index.md
```

All group paths adjusted to remove `docforge/` prefix.

---

### 5️⃣ MkDocs Config Update

`mkdocs.yml` updated to:

* Move `site_name` below theme/plugins
* Use flat navigation paths
* Point Home to `index.md`

---

### 6️⃣ MCP Artifact Regeneration

Updated:

* Function signatures (new parameter)
* Docstrings (reflect `module_is_source`)
* Renderer metadata
* Line numbers

Ensures MCP output matches updated API.

---

## Architectural Outcome

Each project now produces a **valid standalone static site**:

```
site/
  index.html
  assets/
  search/
```

Safe for deployment under:

```
/libs/<project>/
```

No Nginx rewrites required.
No directory-index issues.
No nested-site ambiguity.

---

## Backward Compatibility

* Existing CLI usage remains valid
* `--module-is-source` is optional
* Navigation spec format unchanged (only paths adjusted)

---

## Deployment Impact

After merge:

* Each library can be deployed independently
* Sites can be merged under a shared root without internal conflicts
* Static hosting is predictable and production-safe

---

## Testing

* Verified MkDocs build produces `site/index.html`
* Verified navigation renders correctly
* Verified parent index generation is idempotent
* Regenerated MCP docs and validated schema consistency

---

## Result

The documentation compiler now:

* Produces structurally correct static sites
* Supports flat and source-root modes
* Eliminates 403 root issues
* Scales cleanly across multiple repositories

This aligns doc-forge with proper static-site architectural invariants.

Reviewed-on: #4
Co-authored-by: Vishesh 'ironeagle' Bangotra <aetoskia@gmail.com>
Co-committed-by: Vishesh 'ironeagle' Bangotra <aetoskia@gmail.com>

.run/pytests.run.xml

@@ -1,5 +1,5 @@
 <component name="ProjectRunConfigurationManager">
-  <configuration default="false" name="pytest" type="tests" factoryName="py.test">
+  <configuration default="false" name="pytests" type="tests" factoryName="py.test">
     <module name="docforge" />
     <option name="ENV_FILES" value="" />
     <option name="INTERPRETER_OPTIONS" value="" />

ADS.llm.md

@@ -1,327 +0,0 @@
-# doc-forge — Architecture & Design Specification
-
-**doc-forge** is a renderer-agnostic Python documentation compiler. It converts Python source code and docstrings into a structured, semantic documentation model and then emits multiple downstream representations, including:
-
-* Human-facing documentation sites (MkDocs, Sphinx)
-* Machine-facing documentation bundles (MCP JSON)
-* Live documentation APIs (MCP servers)
-
-This document is the **authoritative design and codebase specification** for the library. It is written to be both **LLM-friendly** and **developer-facing**, and should be treated as the canonical reference for implementation decisions.
-
----
-
-## 1. Design Goals
-
-1. **Single Source of Truth**
-   Python source code and docstrings are the only authoritative input.
-
-2. **Renderer Agnosticism**
-   MkDocs, Sphinx, MCP, or future renderers must not influence the core model.
-
-3. **Deterministic Output**
-   Given the same codebase, outputs must be reproducible.
-
-4. **AI-Native Documentation**
-   Documentation must be structured, queryable, and machine-consumable.
-
-5. **Library-First, CLI-Second**
-   All functionality must be accessible as a Python API. The CLI is a thin wrapper.
-
----
-
-## 2. Core Mental Model
-
-### Fundamental Abstraction
-
-> **The atomic unit of documentation is a Python import path**
-
-Examples:
-
-* `mail_intake`
-* `mail_intake.config`
-* `mail_intake.adapters.base`
-
-Files, Markdown, HTML, and JSON are *representations*, not documentation units.
-
----
-
-## 3. High-Level Architecture
-
-```
-Python Source Code
-        ↓
-Introspection Layer (Griffe)
-        ↓
-Documentation Model (doc-forge core)
-        ↓
-Renderer / Exporter Layer
-   ├── MkDocs
-   ├── Sphinx
-   ├── MCP (static JSON)
-   └── MCP Server (live)
-```
-
-Only the **Documentation Model** is shared across all outputs.
-
----
-
-## 4. Package Layout (Proposed)
-
-```
-docforge/
-├── __init__.py
-├── model/
-│   ├── project.py
-│   ├── module.py
-│   ├── object.py
-│   └── nav.py
-├── loader/
-│   └── griffe_loader.py
-├── renderers/
-│   ├── base.py
-│   ├── mkdocs.py
-│   └── sphinx.py
-├── exporters/
-│   └── mcp.py
-├── server/
-│   └── mcp_server.py
-├── cli/
-│   └── main.py
-└── utils/
-```
-
----
-
-## 5. Documentation Model (Core)
-
-The documentation model is renderer-neutral and must not contain any MkDocs-, Sphinx-, or MCP-specific logic.
-
-### 5.1 Project
-
-```python
-class Project:
-    name: str
-    version: str | None
-    modules: dict[str, Module]
-    nav: Navigation
-```
-
----
-
-### 5.2 Module
-
-```python
-class Module:
-    path: str                # import path
-    docstring: str | None
-    members: dict[str, DocObject]
-```
-
----
-
-### 5.3 DocObject
-
-Represents classes, functions, variables, etc.
-
-```python
-class DocObject:
-    name: str
-    kind: str                # class, function, attribute, module
-    path: str
-    signature: str | None
-    docstring: str | None
-    members: dict[str, DocObject]
-```
-
-Private members (`_name`) are excluded by default.
-
----
-
-### 5.4 Navigation
-
-```python
-class Navigation:
-    entries: list[NavEntry]
-
-class NavEntry:
-    title: str
-    module: str
-```
-
-Navigation is derived, not authored.
-
----
-
-## 6. Introspection Layer
-
-### 6.1 Griffe Loader
-
-Griffe is the **only supported introspection backend**.
-
-Responsibilities:
-
-* Load modules by import path
-* Resolve docstrings, signatures, and members
-* Tolerate alias resolution failures
-
-Output: fully populated `Project` and `Module` objects.
-
----
-
-## 7. Renderer Interface
-
-Renderers consume the documentation model and emit renderer-specific source trees.
-
-```python
-class DocRenderer(Protocol):
-    name: str
-
-    def generate_sources(self, project: Project, out_dir: Path) -> None:
-        """Generate renderer-specific source files."""
-
-    def build(self, config: RendererConfig) -> None:
-        """Build final artifacts (HTML, site, etc.)."""
-
-    def serve(self, config: RendererConfig) -> None:
-        """Serve documentation locally (optional)."""
-```
-
----
-
-## 8. MkDocs Renderer
-
-### Source Generation
-
-* Emits `.md` files
-* One file per module
-* Uses `mkdocstrings` directives exclusively
-
-```md
-# Config
-
-::: mail_intake.config
-```
-
-### Build
-
-* Uses `mkdocs.commands.build`
-
-### Serve
-
-* Uses `mkdocs.commands.serve`
-
-MkDocs-specific configuration lives outside the core model.
-
----
-
-## 9. Sphinx Renderer
-
-### Source Generation
-
-* Emits `.rst` files
-* Uses `autodoc` directives
-
-```rst
-mail_intake.config
-==================
-
-.. automodule:: mail_intake.config
-   :members:
-   :undoc-members:
-```
-
-### Build
-
-* Uses `sphinx.application.Sphinx` directly
-
-### Serve
-
-* Optional (static build is sufficient)
-
----
-
-## 10. MCP Exporter (Static)
-
-The MCP exporter bypasses renderers entirely.
-
-### Output Structure
-
-```
-mcp/
-├── index.json
-├── nav.json
-└── modules/
-    └── package.module.json
-```
-
-### Design Principles
-
-* Alias-safe
-* Deterministic
-* Fully self-contained
-* No Markdown, HTML, or templates
-
----
-
-## 11. MCP Server (Live)
-
-The MCP server exposes documentation as queryable resources.
-
-### Resources
-
-* `docs://index`
-* `docs://nav`
-* `docs://module/{module}`
-
-### Characteristics
-
-* Read-only
-* Stateless
-* Backed by MCP JSON bundle
-
----
-
-## 12. CLI Design
-
-The CLI is a thin orchestration layer.
-
-```bash
-doc-forge generate --renderer mkdocs
-doc-forge generate --renderer sphinx
-
-doc-forge build --renderer mkdocs
-doc-forge serve --renderer mkdocs
-
-doc-forge export mcp
-```
-
-Renderer choice never affects the core model.
-
----
-
-## 13. Explicit Non-Goals
-
-* Markdown authoring
-* Theme design
-* Runtime code execution
-* Code formatting or linting
-
----
-
-## 14. Invariants (Must Never Break)
-
-1. Import paths are canonical identifiers
-2. Core model contains no renderer logic
-3. MCP does not depend on MkDocs or Sphinx
-4. Renderers do not introspect Python directly
-5. All outputs trace back to the same model
-
----
-
-## 15. One-Line Definition
-
-> **doc-forge is a documentation compiler that turns Python code into structured knowledge and emits it through multiple human and machine interfaces.**
-
----
-
-*End of specification.*

docforge.nav.yml

@@ -1,28 +1,26 @@
-home: docforge/index.md
+home: index.md
 groups:
   Loaders:
-    - docforge/loaders/index.md
-    - docforge/loaders/griffe_loader.md
+    - loaders/index.md
+    - loaders/griffe_loader.md
   Models:
-    - docforge/models/index.md
-    - docforge/models/module.md
-    - docforge/models/object.md
-    - docforge/models/project.md
+    - models/index.md
+    - models/module.md
+    - models/object.md
+    - models/project.md
   Navigation:
-    - docforge/nav/index.md
-    - docforge/nav/spec.md
-    - docforge/nav/resolver.md
-    - docforge/nav/mkdocs.md
+    - nav/index.md
+    - nav/spec.md
+    - nav/resolver.md
+    - nav/mkdocs.md
   Renderers:
-    - docforge/renderers/index.md
-    - docforge/renderers/base.md
-    - docforge/renderers/mkdocs_renderer.md
-    - docforge/renderers/mcp_renderer.md
+    - renderers/index.md
+    - renderers/base.md
+    - renderers/mkdocs_renderer.md
+    - renderers/mcp_renderer.md
   CLI:
-    - docforge/cli/index.md
-    - docforge/cli/main.md
-    - docforge/cli/commands.md
-    - docforge/cli/mcp/index.md
-    - docforge/cli/mcp/logic.md
-    - docforge/cli/mkdocs/index.md
-    - docforge/cli/mkdocs/logic.md
+    - cli/index.md
+    - cli/main.md
+    - cli/commands.md
+    - cli/mcp_utils.md
+    - cli/mkdocs_utils.md

docforge/__init__.py

@@ -6,6 +6,35 @@ speed, flexibility, and beautiful output. It decouples the introspection of
 your code from the rendering process, allowing you to generate documentation
 for various platforms (starting with MkDocs) from a single internal models.
 
+## Core Philosophy
+
+`doc-forge` operates on two fundamental principles:
+
+1.  **The Atomic Unit is a Python Import Path**: Documentation is organized around the semantic structure of your code (e.g., `mypackage.utils`), not the filesystem.
+2.  **The Documentation Compiler Paradigm**: We separate documentation into three distinct phases:
+    -   **Front-end (Introspection)**: Static analysis of source code and docstrings.
+    -   **Middle-end (Semantic Model)**: A renderer-neutral internal representation.
+    -   **Back-end (Renderers)**: Generation of human-facing (MkDocs) or machine-facing (MCP) outputs.
+
+## Documentation Design
+
+`doc-forge` is an "AI-Native" documentation compiler. To get the most out of it, design your docstrings with both humans and LLMs in mind:
+
+### For Humans (Readability & Structure)
+- **`__init__.py` as Landing Pages**: Use the docstring of your package's `__init__.py` as the home page. Include overviews, installation instructions, and high-level examples here.
+- **Single Source of Truth**: Keep all technical details in docstrings. This ensures your MkDocs/Sphinx sites stay in sync with the code.
+- **Semantic Hierarchy**: Use standard Markdown headers to structure complex module documentation.
+
+### For LLMs (AI-Native Knowledge)
+- **Model Context Protocol (MCP)**: `doc-forge` exports your docs as structured JSON. This allows AI agents to "understand" your API surface area without layout noise.
+- **Canonical Paths**: Use dotted import paths as primary identifiers. AI tools use these to link code usage to documentation.
+- **Type Annotations**: While not in docstrings, `doc-forge` (via Griffe) extracts signatures. Clean type hints dramatically improve an LLM's ability to generate correct code using your library.
+## Available Commands
+
+- **build**: Build documentation (MkDocs site or MCP resources).
+- **serve**: Serve documentation (MkDocs or MCP).
+- **tree**: Visualize the introspected project structure.
+
 ## Installation
 
 Install using `pip` with the optional `mkdocs` dependencies for a complete setup:
@@ -16,10 +45,14 @@ pip install doc-forge
 
 ## Quick Start
 
-1.  **Generate Markdown Sources**:
-    Introspect your package and create ready-to-use Markdown files:
+1.  **Build Documentation**:
+    Introspect your package and generate documentation in one step:
     ```bash
-    doc-forge generate --module my_package --docs-dir docs
+    # Build MkDocs site
+    doc-forge build --mkdocs --module my_package --site-name "My Docs"
+
+    # Build MCP resources
+    doc-forge build --mcp --module my_package
     ```
 
 2.  **Define Navigation**:
@@ -33,14 +66,13 @@ pip install doc-forge
         - my_package/utils.md
     ```
 
-3.  **Generate MkDocs Configuration**:
+3.  **Preview**:
     ```bash
-    doc-forge mkdocs --site-name "My Awesome Docs"
-    ```
+    # Serve MkDocs site
+    doc-forge serve --mkdocs
 
-4.  **Preview**:
-    ```bash
-    doc-forge serve
+    # Serve MCP documentation
+    doc-forge serve --mcp
     ```
 
 ## Project Structure

docforge/cli/__init__.py

@@ -6,11 +6,9 @@ with doc-forge.
 
 ## Available Commands
 
+- **build**: Build documentation (MkDocs site or MCP resources).
+- **serve**: Serve documentation (MkDocs or MCP).
 - **tree**: Visualize the introspected project structure.
-- **generate**: Create Markdown source files from Python code.
-- **mkdocs**: Generate the primary `mkdocs.yml` configuration.
-- **build**: Build the final documentation site.
-- **serve**: Launch a local development server with live-reloading.
 """
 
 from .main import main

docforge/cli/commands.py

@@ -2,8 +2,9 @@ import click
 from pathlib import Path
 from typing import Sequence, Optional
 from docforge.loaders import GriffeLoader
-from docforge.cli.mkdocs import logic as mkdocs_logic
-from docforge.cli.mcp import logic as mcp_logic
+from docforge.cli import mkdocs_utils
+from docforge.cli import mcp_utils
+
 
 @click.group()
 def cli() -> None:
@@ -13,15 +14,18 @@ def cli() -> None:
     """
     pass
 
+
 @cli.command()
 @click.option("--mcp", is_flag=True, help="Build MCP resources")
 @click.option("--mkdocs", is_flag=True, help="Build MkDocs site")
+@click.option("--module-is-source", is_flag=True, help="Module is source folder and to be treated as root folder")
 @click.option("--module", help="Python module to document")
 @click.option("--project-name", help="Project name override")
 # MkDocs specific
 @click.option("--site-name", help="MkDocs site name")
 @click.option("--docs-dir", type=click.Path(path_type=Path), default=Path("docs"), help="Directory for MD sources")
-@click.option("--nav", "nav_file", type=click.Path(path_type=Path), default=Path("docforge.nav.yml"), help="Nav spec path")
+@click.option("--nav", "nav_file", type=click.Path(path_type=Path), default=Path("docforge.nav.yml"),
+              help="Nav spec path")
 @click.option("--template", type=click.Path(path_type=Path), help="MkDocs template path")
 @click.option("--mkdocs-yml", type=click.Path(path_type=Path), default=Path("mkdocs.yml"), help="Output config path")
 # MCP specific
@@ -29,6 +33,7 @@ def cli() -> None:
 def build(
     mcp: bool,
     mkdocs: bool,
+    module_is_source: bool,
     module: Optional[str],
     project_name: Optional[str],
     site_name: Optional[str],
@@ -40,6 +45,24 @@ def build(
 ) -> None:
     """
     Build documentation (MkDocs site or MCP resources).
+
+    This command orchestrates the full build process:
+    1. Introspects the code (Griffe)
+    2. Renders sources (MkDocs Markdown or MCP JSON)
+    3. (MkDocs only) Generates config and runs the final site build.
+
+    Args:
+        mcp: Use the MCP documentation builder.
+        mkdocs: Use the MkDocs documentation builder.
+        module_is_source: Module is the source folder and to be treated as the root folder.
+        module: The dotted path of the module to the document.
+        project_name: Optional override for the project name.
+        site_name: (MkDocs) The site display name. Defaults to module name.
+        docs_dir: (MkDocs) Target directory for Markdown sources.
+        nav_file: (MkDocs) Path to the docforge.nav.yml specification.
+        template: (MkDocs) Optional custom mkdocs.yml template.
+        mkdocs_yml: (MkDocs) Target path for the generated mkdocs.yml.
+        out_dir: (MCP) Target directory for MCP JSON resources.
     """
     if not mcp and not mkdocs:
         raise click.UsageError("Must specify either --mcp or --mkdocs")
@@ -51,13 +74,18 @@ def build(
             site_name = module
 
         click.echo(f"Generating MkDocs sources in {docs_dir}...")
-        mkdocs_logic.generate_sources(module, project_name, docs_dir)
+        mkdocs_utils.generate_sources(
+            module,
+            docs_dir,
+            project_name,
+            module_is_source,
+        )
 
         click.echo(f"Generating MkDocs config {mkdocs_yml}...")
-        mkdocs_logic.generate_config(docs_dir, nav_file, template, mkdocs_yml, site_name)
+        mkdocs_utils.generate_config(docs_dir, nav_file, template, mkdocs_yml, site_name)
 
         click.echo("Running MkDocs build...")
-        mkdocs_logic.build(mkdocs_yml)
+        mkdocs_utils.build(mkdocs_yml)
         click.echo("MkDocs build completed.")
 
     if mcp:
@@ -65,53 +93,69 @@ def build(
             raise click.UsageError("--module is required for MCP build")
 
         click.echo(f"Generating MCP resources in {out_dir}...")
-        mcp_logic.generate_resources(module, project_name, out_dir)
+        mcp_utils.generate_resources(module, project_name, out_dir)
         click.echo("MCP build completed.")
 
+
 @cli.command()
 @click.option("--mcp", is_flag=True, help="Serve MCP documentation")
 @click.option("--mkdocs", is_flag=True, help="Serve MkDocs site")
+@click.option("--module", help="Python module to serve")
 @click.option("--mkdocs-yml", type=click.Path(path_type=Path), default=Path("mkdocs.yml"), help="MkDocs config path")
 @click.option("--out-dir", type=click.Path(path_type=Path), default=Path("mcp_docs"), help="MCP root directory")
 def serve(
     mcp: bool,
     mkdocs: bool,
+    module: Optional[str],
     mkdocs_yml: Path,
     out_dir: Path,
 ) -> None:
     """
-    Serve documentation.
+    Serve documentation (MkDocs or MCP).
+
+    Args:
+        mcp: Serve MCP resources via an MCP server.
+        mkdocs: Serve the MkDocs site using the built-in development server.
+        module: The dotted path of the module to serve.
+        mkdocs_yml: (MkDocs) Path to the mkdocs.yml configuration.
+        out_dir: (MCP) Path to the mcp_docs/ directory.
     """
     if mcp and mkdocs:
         raise click.UsageError("Cannot specify both --mcp and --mkdocs")
     if not mcp and not mkdocs:
         raise click.UsageError("Must specify either --mcp or --mkdocs")
+    if mcp and not module:
+        raise click.UsageError("--module is required for MCP serve")
 
     if mkdocs:
-        mkdocs_logic.serve(mkdocs_yml)
+        mkdocs_utils.serve(mkdocs_yml)
     elif mcp:
-        mcp_logic.serve(out_dir)
+        mcp_utils.serve(module, out_dir)
+
 
 @cli.command()
 @click.option(
-    "--modules",
-    multiple=True,
+    "--module",
     required=True,
-    help="Python module import paths to introspect",
+    help="Python module import path to introspect",
 )
 @click.option(
     "--project-name",
-    help="Project name (defaults to first module)",
+    help="Project name (defaults to specified module)",
 )
 def tree(
-    modules: Sequence[str],
+    module: str,
     project_name: Optional[str],
 ) -> None:
     """
-    Visualize the project structure.
+    Visualize the project structure in the terminal.
+
+    Args:
+        module: The module import path to recursively introspect.
+        project_name: Optional override for the project name shown at the root.
     """
     loader = GriffeLoader()
-    project = loader.load_project(list(modules), project_name)
+    project = loader.load_project([module], project_name)
 
     click.echo(project.name)
 
@@ -120,9 +164,14 @@ def tree(
         for obj in module.get_all_objects():
             _print_object(obj, indent="│   ")
 
+
 def _print_object(obj, indent: str) -> None:
     """
     Recursive helper to print doc objects and their members to the console.
+
+    Args:
+        obj: The DocObject instance to print.
+        indent: Current line indentation (e.g., '│   ').
     """
     click.echo(f"{indent}├── {obj.name}")
     for member in obj.get_all_members():

docforge/cli/commands.pyi

@@ -0,0 +1,34 @@
+from click.core import Group
+from pathlib import Path
+from typing import Sequence, Optional, Any
+
+cli: Group
+
+def build(
+    mcp: bool,
+    mkdocs: bool,
+    module_is_source: bool,
+    module: Optional[str],
+    project_name: Optional[str],
+    site_name: Optional[str],
+    docs_dir: Path,
+    nav_file: Path,
+    template: Optional[Path],
+    mkdocs_yml: Path,
+    out_dir: Path,
+) -> None: ...
+
+def serve(
+    mcp: bool,
+    mkdocs: bool,
+    module: Optional[str],
+    mkdocs_yml: Path,
+    out_dir: Path,
+) -> None: ...
+
+def tree(
+    module: str,
+    project_name: Optional[str],
+) -> None: ...
+
+def _print_object(obj: Any, indent: str) -> None: ...

docforge/cli/main.py

@@ -1,5 +1,6 @@
 """
-Main entry point for the doc-forge CLI.
+Main entry point for the doc-forge CLI. This module delegates all command
+execution to docforge.cli.commands.
 """
 from docforge.cli.commands import cli
 

docforge/cli/main.pyi

@@ -0,0 +1 @@
+def main() -> None: ...

docforge/cli/mcp_utils.py

@@ -7,6 +7,11 @@ from docforge.servers import MCPServer
 def generate_resources(module: str, project_name: str | None, out_dir: Path) -> None:
     """
     Generate MCP-compatible documentation resources.
+
+    Args:
+        module: The dotted path of the primary module to document.
+        project_name: Optional override for the project name.
+        out_dir: Directory where the MCP JSON resources and nav will be written.
     """
     loader = GriffeLoader()
     discovered_paths = discover_module_paths(module)
@@ -15,9 +20,13 @@ def generate_resources(module: str, project_name: str | None, out_dir: Path) ->
     renderer = MCPRenderer()
     renderer.generate_sources(project, out_dir)
 
-def serve(mcp_root: Path) -> None:
+def serve(module: str, mcp_root: Path) -> None:
     """
-    Serve MCP documentation.
+    Serve MCP documentation from a pre-built bundle.
+
+    Args:
+        module: The dotted path of the primary module to serve.
+        mcp_root: Path to the directory containing index.json, nav.json, and modules/.
     """
     if not mcp_root.exists():
         raise click.ClickException(f"mcp_docs directory not found: {mcp_root}")
@@ -34,6 +43,6 @@ def serve(mcp_root: Path) -> None:
 
     server = MCPServer(
         mcp_root=mcp_root,
-        name="doc-forge-mcp",
+        name=f"{module}-mcp",
     )
     server.run()

docforge/cli/mcp_utils.pyi

@@ -0,0 +1,4 @@
+from pathlib import Path
+
+def generate_resources(module: str, project_name: str | None, out_dir: Path) -> None: ...
+def serve(module: str, mcp_root: Path) -> None: ...

docforge/cli/mkdocs_utils.py

@@ -6,20 +6,42 @@ from docforge.loaders import GriffeLoader, discover_module_paths
 from docforge.renderers import MkDocsRenderer
 from docforge.nav import load_nav_spec, resolve_nav, MkDocsNavEmitter
 
-def generate_sources(module: str, project_name: str | None, docs_dir: Path) -> None:
+def generate_sources(
+    module: str,
+    docs_dir: Path,
+    project_name: str | None = None,
+    module_is_source: bool | None = None,
+) -> None:
     """
     Generate Markdown source files for the specified module.
+
+    Args:
+        module: The dotted path of the primary module to document.
+        project_name: Optional override for the project name.
+        docs_dir: Directory where the generated Markdown files will be written.
+        module_is_source: Module is the source folder and to be treated as the root folder.
     """
     loader = GriffeLoader()
     discovered_paths = discover_module_paths(module)
     project = loader.load_project(discovered_paths, project_name)
 
     renderer = MkDocsRenderer()
-    renderer.generate_sources(project, docs_dir)
+    renderer.generate_sources(
+        project,
+        docs_dir,
+        module_is_source,
+    )
 
 def generate_config(docs_dir: Path, nav_file: Path, template: Path | None, out: Path, site_name: str) -> None:
     """
     Generate an mkdocs.yml configuration file.
+
+    Args:
+        docs_dir: Path to the directory containing documentation Markdown files.
+        nav_file: Path to the docforge.nav.yml specification.
+        template: Optional path to an mkdocs.yml template (overrides built-in).
+        out: Path where the final mkdocs.yml will be written.
+        site_name: The display name for the documentation site.
     """
     if not nav_file.exists():
         raise click.FileError(str(nav_file), hint="Nav spec not found")
@@ -49,6 +71,9 @@ def generate_config(docs_dir: Path, nav_file: Path, template: Path | None, out:
 def build(mkdocs_yml: Path) -> None:
     """
     Build the documentation site using MkDocs.
+
+    Args:
+        mkdocs_yml: Path to the mkdocs.yml configuration file.
     """
     if not mkdocs_yml.exists():
         raise click.ClickException(f"mkdocs.yml not found: {mkdocs_yml}")
@@ -61,6 +86,9 @@ def build(mkdocs_yml: Path) -> None:
 def serve(mkdocs_yml: Path) -> None:
     """
     Serve the documentation site with live-reload using MkDocs.
+
+    Args:
+        mkdocs_yml: Path to the mkdocs.yml configuration file.
     """
     if not mkdocs_yml.exists():
         raise click.ClickException(f"mkdocs.yml not found: {mkdocs_yml}")

docforge/cli/mkdocs_utils.pyi

@@ -0,0 +1,11 @@
+from pathlib import Path
+
+def generate_sources(
+    module: str,
+    docs_dir: Path,
+    project_name: str | None = None,
+    module_is_source: bool | None = None,
+) -> None: ...
+def generate_config(docs_dir: Path, nav_file: Path, template: Path | None, out: Path, site_name: str) -> None: ...
+def build(mkdocs_yml: Path) -> None: ...
+def serve(mkdocs_yml: Path) -> None: ...

docforge/renderers/mcp_renderer.py

@@ -15,6 +15,10 @@ class MCPRenderer:
     def generate_sources(self, project: Project, out_dir: Path) -> None:
         """
         Generate MCP-compatible JSON resources and navigation for the project.
+
+        Args:
+            project: The project model to render.
+            out_dir: Target directory for the generated JSON files.
         """
         modules_dir = out_dir / "modules"
         modules_dir.mkdir(parents=True, exist_ok=True)
@@ -50,7 +54,11 @@ class MCPRenderer:
 
     def _write_module(self, module: Module, modules_dir: Path) -> None:
         """
-        Serialize a module into an MCP JSON resource.
+        Serialize a module into an MCP JSON resource on disk.
+
+        Args:
+            module: The module instance to serialize.
+            modules_dir: The directory where the module JSON file should be written.
         """
         payload = {
             "module": module.path,
@@ -64,6 +72,12 @@ class MCPRenderer:
     def _render_module(self, module: Module) -> Dict:
         """
         Render a Module into MCP-friendly structured data.
+
+        Args:
+            module: The module instance to render.
+
+        Returns:
+            A dictionary following the MCP documentation resource schema.
         """
         data: Dict = {
             "path": module.path,
@@ -79,6 +93,12 @@ class MCPRenderer:
     def _render_object(self, obj: DocObject) -> Dict:
         """
         Recursively render a DocObject into structured MCP data.
+
+        Args:
+            obj: The documented object (class, func, etc.) to render.
+
+        Returns:
+            A dictionary representing the object and its members.
         """
         data: Dict = {
             "name": obj.name,

docforge/renderers/mkdocs_renderer.py

@@ -1,11 +1,16 @@
 """
-This module implements the MkDocsRenderer, which generates Markdown source files
-compatible with the MkDocs 'material' theme and 'mkdocstrings' extension.
+MkDocsRenderer
+
+Generates Markdown source files compatible with MkDocs Material
+and mkdocstrings, ensuring:
+
+- Root index.md always exists
+- Parent package indexes are created automatically
+- Child modules are linked in parent index files
 """
 
 from pathlib import Path
-
-from docforge.models import Project
+from docforge.models import Project, Module
 
 
 class MkDocsRenderer:
@@ -16,7 +21,15 @@ class MkDocsRenderer:
 
     name = "mkdocs"
 
-    def generate_sources(self, project: Project, out_dir: Path) -> None:
+    # -------------------------
+    # Public API
+    # -------------------------
+    def generate_sources(
+        self,
+        project: Project,
+        out_dir: Path,
+        module_is_source: bool | None = None,
+    ) -> None:
         """
         Produce a set of Markdown files in the output directory based on the
         provided Project models.
@@ -24,7 +37,11 @@ class MkDocsRenderer:
         Args:
             project: The project models to render.
             out_dir: Target directory for documentation files.
+            module_is_source: Module is the source folder and to be treated as the root folder.
         """
+        out_dir.mkdir(parents=True, exist_ok=True)
+        self._ensure_root_index(project, out_dir)
+
         modules = list(project.get_all_modules())
         paths = {m.path for m in modules}
 
@@ -35,12 +52,23 @@ class MkDocsRenderer:
         }
 
         for module in modules:
-            self._write_module(module, packages, out_dir)
+            self._write_module(
+                module,
+                packages,
+                out_dir,
+                module_is_source,
+            )
 
     # -------------------------
     # Internal helpers
     # -------------------------
-    def _write_module(self, module, packages: set[str], out_dir: Path) -> None:
+    def _write_module(
+        self,
+        module: Module,
+        packages: set[str],
+        out_dir: Path,
+        module_is_source: bool | None = None,
+    ) -> None:
         """
         Write a single module's documentation file. Packages are written as
         'index.md' inside their respective directories.
@@ -49,30 +77,36 @@ class MkDocsRenderer:
             module: The module to write.
             packages: A set of module paths that are identified as packages.
             out_dir: The base output directory.
+            module_is_source: Module is the source folder and to be treated as the root folder.
         """
         parts = module.path.split(".")
 
+        if module_is_source:
+            module_name, parts = parts[0], parts[1:]
+        else:
+            module_name, parts = parts[0], parts
+
         if module.path in packages:
-            # package → index.md
+            # Package → directory/index.md
             dir_path = out_dir.joinpath(*parts)
             dir_path.mkdir(parents=True, exist_ok=True)
-
             md_path = dir_path / "index.md"
-            title = parts[-1].replace("_", " ").title()
+            link_target = f"{parts[-1]}/" if parts else None
         else:
-            # leaf module → <name>.md
+            # Leaf module → parent_dir/<name>.md
             dir_path = out_dir.joinpath(*parts[:-1])
             dir_path.mkdir(parents=True, exist_ok=True)
-
             md_path = dir_path / f"{parts[-1]}.md"
-            title = parts[-1].replace("_", " ").title()
+            link_target = f"{parts[-1]}.md" if parts else None
 
+        title = parts[-1].replace("_", " ").title() if parts else module_name
         content = self._render_markdown(title, module.path)
 
-        if md_path.exists() and md_path.read_text(encoding="utf-8") == content:
-            return
+        if not md_path.exists() or md_path.read_text(encoding="utf-8") != content:
+            md_path.write_text(content, encoding="utf-8")
 
-        md_path.write_text(content, encoding="utf-8")
+        if not module_is_source:
+            self._ensure_parent_index(parts, out_dir, link_target, title)
 
     def _render_markdown(self, title: str, module_path: str) -> str:
         """
@@ -89,3 +123,46 @@ class MkDocsRenderer:
             f"# {title}\n\n"
             f"::: {module_path}\n"
         )
+
+    def _ensure_root_index(
+        self,
+        project: Project,
+        out_dir: Path
+    ) -> None:
+        root_index = out_dir / "index.md"
+
+        if not root_index.exists():
+            root_index.write_text(
+                f"# {project.name}\n\n"
+                "## Modules\n\n",
+                encoding="utf-8",
+            )
+
+    def _ensure_parent_index(
+        self,
+        parts: list[str],
+        out_dir: Path,
+        link_target: str,
+        title: str,
+    ) -> None:
+        if len(parts) == 1:
+            parent_index = out_dir / "index.md"
+            link = f"- [{title}]({link_target})\n"
+        else:
+            parent_dir = out_dir.joinpath(*parts[:-1])
+            parent_dir.mkdir(parents=True, exist_ok=True)
+            parent_index = parent_dir / "index.md"
+
+            link = f"- [{title}]({link_target})\n"
+
+            if not parent_index.exists():
+                parent_title = parts[-2].replace("_", " ").title()
+                parent_index.write_text(
+                    f"# {parent_title}\n\n",
+                    encoding="utf-8",
+                )
+
+        content = parent_index.read_text(encoding="utf-8")
+
+        if link not in content:
+            parent_index.write_text(content + link, encoding="utf-8")

docforge/renderers/mkdocs_renderer.pyi

@@ -1,17 +1,27 @@
 from pathlib import Path
-from typing import Set
-
 from docforge.models import Project, Module
 
 
 class MkDocsRenderer:
     name: str
 
-    def generate_sources(self, project: Project, out_dir: Path) -> None: ...
+    def generate_sources(
+        self,
+        project: Project,
+        out_dir: Path,
+        module_is_source: bool | None = None,
+    ) -> None: ...
+
     def _write_module(
         self,
         module: Module,
-        packages: Set[str],
+        packages: set[str],
         out_dir: Path,
+        module_is_source: bool | None = None,
     ) -> None: ...
+
     def _render_markdown(self, title: str, module_path: str) -> str: ...
+
+    def _ensure_root_index(self, project, out_dir) -> None: ...
+
+    def _ensure_parent_index(self, parts, out_dir, link_target, title) -> None: ...

docs/cli/mcp_utils.md

@@ -0,0 +1,3 @@
+# Mcp Utils
+
+::: docforge.cli.mcp_utils

docs/cli/mkdocs_utils.md

@@ -0,0 +1,3 @@
+# Mkdocs Utils
+
+::: docforge.cli.mkdocs_utils

docs/docforge/cli/mcp/index.md

@@ -1,3 +0,0 @@
-# Mcp
-
-::: docforge.cli.mcp

docs/docforge/cli/mcp/logic.md

@@ -1,3 +0,0 @@
-# Logic
-
-::: docforge.cli.mcp.logic

docs/docforge/cli/mkdocs/index.md

@@ -1,3 +0,0 @@
-# Mkdocs
-
-::: docforge.cli.mkdocs

docs/docforge/cli/mkdocs/logic.md

@@ -1,3 +0,0 @@
-# Logic
-
-::: docforge.cli.mkdocs.logic

docs/index.md

@@ -1,3 +1,3 @@
-# Docforge
+# docforge
 
 ::: docforge

mcp_docs/index.json

@@ -1,6 +1,6 @@
 {
   "project": "docforge",
   "type": "docforge-model",
-  "modules_count": 24,
+  "modules_count": 22,
   "source": "docforge"
 }

mcp_docs/modules/docforge.cli.commands.json

@@ -55,59 +55,59 @@
           }
         }
       },
-      "mkdocs_logic": {
-        "name": "mkdocs_logic",
+      "mkdocs_utils": {
+        "name": "mkdocs_utils",
         "kind": "module",
-        "path": "docforge.cli.commands.mkdocs_logic",
-        "signature": "<bound method Alias.signature of Alias('mkdocs_logic', 'docforge.cli.mkdocs.logic')>",
+        "path": "docforge.cli.commands.mkdocs_utils",
+        "signature": "<bound method Alias.signature of Alias('mkdocs_utils', 'docforge.cli.mkdocs_utils')>",
         "docstring": null,
         "members": {
           "Path": {
             "name": "Path",
             "kind": "alias",
-            "path": "docforge.cli.commands.mkdocs_logic.Path",
-            "signature": "<bound method Alias.signature of Alias('Path', 'docforge.cli.mkdocs.logic.Path')>",
+            "path": "docforge.cli.commands.mkdocs_utils.Path",
+            "signature": "<bound method Alias.signature of Alias('Path', 'docforge.cli.mkdocs_utils.Path')>",
             "docstring": null
           },
           "resources": {
             "name": "resources",
             "kind": "alias",
-            "path": "docforge.cli.commands.mkdocs_logic.resources",
-            "signature": "<bound method Alias.signature of Alias('resources', 'docforge.cli.mkdocs.logic.resources')>",
+            "path": "docforge.cli.commands.mkdocs_utils.resources",
+            "signature": "<bound method Alias.signature of Alias('resources', 'docforge.cli.mkdocs_utils.resources')>",
             "docstring": null
           },
           "click": {
             "name": "click",
             "kind": "alias",
-            "path": "docforge.cli.commands.mkdocs_logic.click",
-            "signature": "<bound method Alias.signature of Alias('click', 'docforge.cli.mkdocs.logic.click')>",
+            "path": "docforge.cli.commands.mkdocs_utils.click",
+            "signature": "<bound method Alias.signature of Alias('click', 'docforge.cli.mkdocs_utils.click')>",
             "docstring": null
           },
           "yaml": {
             "name": "yaml",
             "kind": "alias",
-            "path": "docforge.cli.commands.mkdocs_logic.yaml",
-            "signature": "<bound method Alias.signature of Alias('yaml', 'docforge.cli.mkdocs.logic.yaml')>",
+            "path": "docforge.cli.commands.mkdocs_utils.yaml",
+            "signature": "<bound method Alias.signature of Alias('yaml', 'docforge.cli.mkdocs_utils.yaml')>",
             "docstring": null
           },
           "GriffeLoader": {
             "name": "GriffeLoader",
             "kind": "class",
-            "path": "docforge.cli.commands.mkdocs_logic.GriffeLoader",
-            "signature": "<bound method Alias.signature of Alias('GriffeLoader', 'docforge.cli.mkdocs.logic.GriffeLoader')>",
+            "path": "docforge.cli.commands.mkdocs_utils.GriffeLoader",
+            "signature": "<bound method Alias.signature of Alias('GriffeLoader', 'docforge.cli.mkdocs_utils.GriffeLoader')>",
             "docstring": "Loads Python modules and extracts documentation using the Griffe introspection engine.",
             "members": {
               "load_project": {
                 "name": "load_project",
                 "kind": "function",
-                "path": "docforge.cli.commands.mkdocs_logic.GriffeLoader.load_project",
+                "path": "docforge.cli.commands.mkdocs_utils.GriffeLoader.load_project",
                 "signature": "<bound method Alias.signature of Alias('load_project', 'docforge.loaders.griffe_loader.GriffeLoader.load_project')>",
                 "docstring": "Load multiple modules and combine them into a single Project models.\n\nArgs:\n    module_paths: A list of dotted paths to the modules to load.\n    project_name: Optional name for the project. Defaults to the first module name.\n    skip_import_errors: If True, modules that fail to import will be skipped.\n\nReturns:\n    A Project instance containing the loaded modules."
               },
               "load_module": {
                 "name": "load_module",
                 "kind": "function",
-                "path": "docforge.cli.commands.mkdocs_logic.GriffeLoader.load_module",
+                "path": "docforge.cli.commands.mkdocs_utils.GriffeLoader.load_module",
                 "signature": "<bound method Alias.signature of Alias('load_module', 'docforge.loaders.griffe_loader.GriffeLoader.load_module')>",
                 "docstring": "Load a single module and convert its introspection data into the docforge models.\n\nArgs:\n    path: The dotted path of the module to load.\n\nReturns:\n    A Module instance."
               }
@@ -116,58 +116,58 @@
           "discover_module_paths": {
             "name": "discover_module_paths",
             "kind": "function",
-            "path": "docforge.cli.commands.mkdocs_logic.discover_module_paths",
-            "signature": "<bound method Alias.signature of Alias('discover_module_paths', 'docforge.cli.mkdocs.logic.discover_module_paths')>",
+            "path": "docforge.cli.commands.mkdocs_utils.discover_module_paths",
+            "signature": "<bound method Alias.signature of Alias('discover_module_paths', 'docforge.cli.mkdocs_utils.discover_module_paths')>",
             "docstring": "Discover all Python modules under a package via filesystem traversal.\n\nRules:\n- Directory with __init__.py is treated as a package.\n- Any .py file is treated as a module.\n- All paths are converted to dotted module paths.\n\nArgs:\n    module_name: The name of the package to discover.\n    project_root: The root directory of the project. Defaults to current working directory.\n\nReturns:\n    A sorted list of dotted module paths."
           },
           "MkDocsRenderer": {
             "name": "MkDocsRenderer",
             "kind": "class",
-            "path": "docforge.cli.commands.mkdocs_logic.MkDocsRenderer",
-            "signature": "<bound method Alias.signature of Alias('MkDocsRenderer', 'docforge.cli.mkdocs.logic.MkDocsRenderer')>",
+            "path": "docforge.cli.commands.mkdocs_utils.MkDocsRenderer",
+            "signature": "<bound method Alias.signature of Alias('MkDocsRenderer', 'docforge.cli.mkdocs_utils.MkDocsRenderer')>",
             "docstring": "Renderer that generates Markdown source files formatted for the MkDocs\n'mkdocstrings' plugin.",
             "members": {
               "name": {
                 "name": "name",
                 "kind": "attribute",
-                "path": "docforge.cli.commands.mkdocs_logic.MkDocsRenderer.name",
+                "path": "docforge.cli.commands.mkdocs_utils.MkDocsRenderer.name",
                 "signature": "<bound method Alias.signature of Alias('name', 'docforge.renderers.mkdocs_renderer.MkDocsRenderer.name')>",
                 "docstring": null
               },
               "generate_sources": {
                 "name": "generate_sources",
                 "kind": "function",
-                "path": "docforge.cli.commands.mkdocs_logic.MkDocsRenderer.generate_sources",
+                "path": "docforge.cli.commands.mkdocs_utils.MkDocsRenderer.generate_sources",
                 "signature": "<bound method Alias.signature of Alias('generate_sources', 'docforge.renderers.mkdocs_renderer.MkDocsRenderer.generate_sources')>",
-                "docstring": "Produce a set of Markdown files in the output directory based on the\nprovided Project models.\n\nArgs:\n    project: The project models to render.\n    out_dir: Target directory for documentation files."
+                "docstring": "Produce a set of Markdown files in the output directory based on the\nprovided Project models.\n\nArgs:\n    project: The project models to render.\n    out_dir: Target directory for documentation files.\n    module_is_source: Module is the source folder and to be treated as the root folder."
               }
             }
           },
           "load_nav_spec": {
             "name": "load_nav_spec",
             "kind": "function",
-            "path": "docforge.cli.commands.mkdocs_logic.load_nav_spec",
-            "signature": "<bound method Alias.signature of Alias('load_nav_spec', 'docforge.cli.mkdocs.logic.load_nav_spec')>",
+            "path": "docforge.cli.commands.mkdocs_utils.load_nav_spec",
+            "signature": "<bound method Alias.signature of Alias('load_nav_spec', 'docforge.cli.mkdocs_utils.load_nav_spec')>",
             "docstring": "Utility function to load a NavSpec from a file.\n\nArgs:\n    path: Path to the navigation specification file.\n\nReturns:\n    A loaded NavSpec instance."
           },
           "resolve_nav": {
             "name": "resolve_nav",
             "kind": "function",
-            "path": "docforge.cli.commands.mkdocs_logic.resolve_nav",
-            "signature": "<bound method Alias.signature of Alias('resolve_nav', 'docforge.cli.mkdocs.logic.resolve_nav')>",
+            "path": "docforge.cli.commands.mkdocs_utils.resolve_nav",
+            "signature": "<bound method Alias.signature of Alias('resolve_nav', 'docforge.cli.mkdocs_utils.resolve_nav')>",
             "docstring": "Create a ResolvedNav by processing a NavSpec against the filesystem.\nThis expands globs and validates the existence of referenced files.\n\nArgs:\n    spec: The navigation specification to resolve.\n    docs_root: The root directory for documentation files.\n\nReturns:\n    A ResolvedNav instance.\n\nRaises:\n    FileNotFoundError: If a pattern doesn't match any files or the docs_root doesn't exist."
           },
           "MkDocsNavEmitter": {
             "name": "MkDocsNavEmitter",
             "kind": "class",
-            "path": "docforge.cli.commands.mkdocs_logic.MkDocsNavEmitter",
-            "signature": "<bound method Alias.signature of Alias('MkDocsNavEmitter', 'docforge.cli.mkdocs.logic.MkDocsNavEmitter')>",
+            "path": "docforge.cli.commands.mkdocs_utils.MkDocsNavEmitter",
+            "signature": "<bound method Alias.signature of Alias('MkDocsNavEmitter', 'docforge.cli.mkdocs_utils.MkDocsNavEmitter')>",
             "docstring": "Emitter responsible for transforming a ResolvedNav into an MkDocs-compatible\nnavigation structure.",
             "members": {
               "emit": {
                 "name": "emit",
                 "kind": "function",
-                "path": "docforge.cli.commands.mkdocs_logic.MkDocsNavEmitter.emit",
+                "path": "docforge.cli.commands.mkdocs_utils.MkDocsNavEmitter.emit",
                 "signature": "<bound method Alias.signature of Alias('emit', 'docforge.nav.mkdocs.MkDocsNavEmitter.emit')>",
                 "docstring": "Generate a list of navigation entries for mkdocs.yml.\n\nArgs:\n    nav: The resolved navigation data.\n\nReturns:\n    A list of dictionary mappings representing the MkDocs navigation."
               }
@@ -176,72 +176,72 @@
           "generate_sources": {
             "name": "generate_sources",
             "kind": "function",
-            "path": "docforge.cli.commands.mkdocs_logic.generate_sources",
-            "signature": "<bound method Alias.signature of Alias('generate_sources', 'docforge.cli.mkdocs.logic.generate_sources')>",
-            "docstring": "Generate Markdown source files for the specified module."
+            "path": "docforge.cli.commands.mkdocs_utils.generate_sources",
+            "signature": "<bound method Alias.signature of Alias('generate_sources', 'docforge.cli.mkdocs_utils.generate_sources')>",
+            "docstring": "Generate Markdown source files for the specified module.\n\nArgs:\n    module: The dotted path of the primary module to document.\n    project_name: Optional override for the project name.\n    docs_dir: Directory where the generated Markdown files will be written.\n    module_is_source: Module is the source folder and to be treated as the root folder."
           },
           "generate_config": {
             "name": "generate_config",
             "kind": "function",
-            "path": "docforge.cli.commands.mkdocs_logic.generate_config",
-            "signature": "<bound method Alias.signature of Alias('generate_config', 'docforge.cli.mkdocs.logic.generate_config')>",
-            "docstring": "Generate an mkdocs.yml configuration file."
+            "path": "docforge.cli.commands.mkdocs_utils.generate_config",
+            "signature": "<bound method Alias.signature of Alias('generate_config', 'docforge.cli.mkdocs_utils.generate_config')>",
+            "docstring": "Generate an mkdocs.yml configuration file.\n\nArgs:\n    docs_dir: Path to the directory containing documentation Markdown files.\n    nav_file: Path to the docforge.nav.yml specification.\n    template: Optional path to an mkdocs.yml template (overrides built-in).\n    out: Path where the final mkdocs.yml will be written.\n    site_name: The display name for the documentation site."
           },
           "build": {
             "name": "build",
             "kind": "function",
-            "path": "docforge.cli.commands.mkdocs_logic.build",
-            "signature": "<bound method Alias.signature of Alias('build', 'docforge.cli.mkdocs.logic.build')>",
-            "docstring": "Build the documentation site using MkDocs."
+            "path": "docforge.cli.commands.mkdocs_utils.build",
+            "signature": "<bound method Alias.signature of Alias('build', 'docforge.cli.mkdocs_utils.build')>",
+            "docstring": "Build the documentation site using MkDocs.\n\nArgs:\n    mkdocs_yml: Path to the mkdocs.yml configuration file."
           },
           "serve": {
             "name": "serve",
             "kind": "function",
-            "path": "docforge.cli.commands.mkdocs_logic.serve",
-            "signature": "<bound method Alias.signature of Alias('serve', 'docforge.cli.mkdocs.logic.serve')>",
-            "docstring": "Serve the documentation site with live-reload using MkDocs."
+            "path": "docforge.cli.commands.mkdocs_utils.serve",
+            "signature": "<bound method Alias.signature of Alias('serve', 'docforge.cli.mkdocs_utils.serve')>",
+            "docstring": "Serve the documentation site with live-reload using MkDocs.\n\nArgs:\n    mkdocs_yml: Path to the mkdocs.yml configuration file."
           }
         }
       },
-      "mcp_logic": {
-        "name": "mcp_logic",
+      "mcp_utils": {
+        "name": "mcp_utils",
         "kind": "module",
-        "path": "docforge.cli.commands.mcp_logic",
-        "signature": "<bound method Alias.signature of Alias('mcp_logic', 'docforge.cli.mcp.logic')>",
+        "path": "docforge.cli.commands.mcp_utils",
+        "signature": "<bound method Alias.signature of Alias('mcp_utils', 'docforge.cli.mcp_utils')>",
         "docstring": null,
         "members": {
           "Path": {
             "name": "Path",
             "kind": "alias",
-            "path": "docforge.cli.commands.mcp_logic.Path",
-            "signature": "<bound method Alias.signature of Alias('Path', 'docforge.cli.mcp.logic.Path')>",
+            "path": "docforge.cli.commands.mcp_utils.Path",
+            "signature": "<bound method Alias.signature of Alias('Path', 'docforge.cli.mcp_utils.Path')>",
             "docstring": null
           },
           "click": {
             "name": "click",
             "kind": "alias",
-            "path": "docforge.cli.commands.mcp_logic.click",
-            "signature": "<bound method Alias.signature of Alias('click', 'docforge.cli.mcp.logic.click')>",
+            "path": "docforge.cli.commands.mcp_utils.click",
+            "signature": "<bound method Alias.signature of Alias('click', 'docforge.cli.mcp_utils.click')>",
             "docstring": null
           },
           "GriffeLoader": {
             "name": "GriffeLoader",
             "kind": "class",
-            "path": "docforge.cli.commands.mcp_logic.GriffeLoader",
-            "signature": "<bound method Alias.signature of Alias('GriffeLoader', 'docforge.cli.mcp.logic.GriffeLoader')>",
+            "path": "docforge.cli.commands.mcp_utils.GriffeLoader",
+            "signature": "<bound method Alias.signature of Alias('GriffeLoader', 'docforge.cli.mcp_utils.GriffeLoader')>",
             "docstring": "Loads Python modules and extracts documentation using the Griffe introspection engine.",
             "members": {
               "load_project": {
                 "name": "load_project",
                 "kind": "function",
-                "path": "docforge.cli.commands.mcp_logic.GriffeLoader.load_project",
+                "path": "docforge.cli.commands.mcp_utils.GriffeLoader.load_project",
                 "signature": "<bound method Alias.signature of Alias('load_project', 'docforge.loaders.griffe_loader.GriffeLoader.load_project')>",
                 "docstring": "Load multiple modules and combine them into a single Project models.\n\nArgs:\n    module_paths: A list of dotted paths to the modules to load.\n    project_name: Optional name for the project. Defaults to the first module name.\n    skip_import_errors: If True, modules that fail to import will be skipped.\n\nReturns:\n    A Project instance containing the loaded modules."
               },
               "load_module": {
                 "name": "load_module",
                 "kind": "function",
-                "path": "docforge.cli.commands.mcp_logic.GriffeLoader.load_module",
+                "path": "docforge.cli.commands.mcp_utils.GriffeLoader.load_module",
                 "signature": "<bound method Alias.signature of Alias('load_module', 'docforge.loaders.griffe_loader.GriffeLoader.load_module')>",
                 "docstring": "Load a single module and convert its introspection data into the docforge models.\n\nArgs:\n    path: The dotted path of the module to load.\n\nReturns:\n    A Module instance."
               }
@@ -250,58 +250,58 @@
           "discover_module_paths": {
             "name": "discover_module_paths",
             "kind": "function",
-            "path": "docforge.cli.commands.mcp_logic.discover_module_paths",
-            "signature": "<bound method Alias.signature of Alias('discover_module_paths', 'docforge.cli.mcp.logic.discover_module_paths')>",
+            "path": "docforge.cli.commands.mcp_utils.discover_module_paths",
+            "signature": "<bound method Alias.signature of Alias('discover_module_paths', 'docforge.cli.mcp_utils.discover_module_paths')>",
             "docstring": "Discover all Python modules under a package via filesystem traversal.\n\nRules:\n- Directory with __init__.py is treated as a package.\n- Any .py file is treated as a module.\n- All paths are converted to dotted module paths.\n\nArgs:\n    module_name: The name of the package to discover.\n    project_root: The root directory of the project. Defaults to current working directory.\n\nReturns:\n    A sorted list of dotted module paths."
           },
           "MCPRenderer": {
             "name": "MCPRenderer",
             "kind": "class",
-            "path": "docforge.cli.commands.mcp_logic.MCPRenderer",
-            "signature": "<bound method Alias.signature of Alias('MCPRenderer', 'docforge.cli.mcp.logic.MCPRenderer')>",
+            "path": "docforge.cli.commands.mcp_utils.MCPRenderer",
+            "signature": "<bound method Alias.signature of Alias('MCPRenderer', 'docforge.cli.mcp_utils.MCPRenderer')>",
             "docstring": "Renderer that emits MCP-native JSON resources from docforge models.",
             "members": {
               "name": {
                 "name": "name",
                 "kind": "attribute",
-                "path": "docforge.cli.commands.mcp_logic.MCPRenderer.name",
+                "path": "docforge.cli.commands.mcp_utils.MCPRenderer.name",
                 "signature": "<bound method Alias.signature of Alias('name', 'docforge.renderers.mcp_renderer.MCPRenderer.name')>",
                 "docstring": null
               },
               "generate_sources": {
                 "name": "generate_sources",
                 "kind": "function",
-                "path": "docforge.cli.commands.mcp_logic.MCPRenderer.generate_sources",
+                "path": "docforge.cli.commands.mcp_utils.MCPRenderer.generate_sources",
                 "signature": "<bound method Alias.signature of Alias('generate_sources', 'docforge.renderers.mcp_renderer.MCPRenderer.generate_sources')>",
-                "docstring": "Generate MCP-compatible JSON resources and navigation for the project."
+                "docstring": "Generate MCP-compatible JSON resources and navigation for the project.\n\nArgs:\n    project: The project model to render.\n    out_dir: Target directory for the generated JSON files."
               }
             }
           },
           "MCPServer": {
             "name": "MCPServer",
             "kind": "class",
-            "path": "docforge.cli.commands.mcp_logic.MCPServer",
-            "signature": "<bound method Alias.signature of Alias('MCPServer', 'docforge.cli.mcp.logic.MCPServer')>",
+            "path": "docforge.cli.commands.mcp_utils.MCPServer",
+            "signature": "<bound method Alias.signature of Alias('MCPServer', 'docforge.cli.mcp_utils.MCPServer')>",
             "docstring": "MCP server for serving a pre-built MCP documentation bundle.",
             "members": {
               "mcp_root": {
                 "name": "mcp_root",
                 "kind": "attribute",
-                "path": "docforge.cli.commands.mcp_logic.MCPServer.mcp_root",
+                "path": "docforge.cli.commands.mcp_utils.MCPServer.mcp_root",
                 "signature": "<bound method Alias.signature of Alias('mcp_root', 'docforge.servers.mcp_server.MCPServer.mcp_root')>",
                 "docstring": null
               },
               "app": {
                 "name": "app",
                 "kind": "attribute",
-                "path": "docforge.cli.commands.mcp_logic.MCPServer.app",
+                "path": "docforge.cli.commands.mcp_utils.MCPServer.app",
                 "signature": "<bound method Alias.signature of Alias('app', 'docforge.servers.mcp_server.MCPServer.app')>",
                 "docstring": null
               },
               "run": {
                 "name": "run",
                 "kind": "function",
-                "path": "docforge.cli.commands.mcp_logic.MCPServer.run",
+                "path": "docforge.cli.commands.mcp_utils.MCPServer.run",
                 "signature": "<bound method Alias.signature of Alias('run', 'docforge.servers.mcp_server.MCPServer.run')>",
                 "docstring": "Start the MCP server.\n\nArgs:\n    transport: MCP transport (default: streamable-http)"
               }
@@ -310,46 +310,60 @@
           "generate_resources": {
             "name": "generate_resources",
             "kind": "function",
-            "path": "docforge.cli.commands.mcp_logic.generate_resources",
-            "signature": "<bound method Alias.signature of Alias('generate_resources', 'docforge.cli.mcp.logic.generate_resources')>",
-            "docstring": "Generate MCP-compatible documentation resources."
+            "path": "docforge.cli.commands.mcp_utils.generate_resources",
+            "signature": "<bound method Alias.signature of Alias('generate_resources', 'docforge.cli.mcp_utils.generate_resources')>",
+            "docstring": "Generate MCP-compatible documentation resources.\n\nArgs:\n    module: The dotted path of the primary module to document.\n    project_name: Optional override for the project name.\n    out_dir: Directory where the MCP JSON resources and nav will be written."
           },
           "serve": {
             "name": "serve",
             "kind": "function",
-            "path": "docforge.cli.commands.mcp_logic.serve",
-            "signature": "<bound method Alias.signature of Alias('serve', 'docforge.cli.mcp.logic.serve')>",
-            "docstring": "Serve MCP documentation."
+            "path": "docforge.cli.commands.mcp_utils.serve",
+            "signature": "<bound method Alias.signature of Alias('serve', 'docforge.cli.mcp_utils.serve')>",
+            "docstring": "Serve MCP documentation from a pre-built bundle.\n\nArgs:\n    module: The dotted path of the primary module to serve.\n    mcp_root: Path to the directory containing index.json, nav.json, and modules/."
           }
         }
       },
       "cli": {
         "name": "cli",
-        "kind": "function",
+        "kind": "attribute",
         "path": "docforge.cli.commands.cli",
-        "signature": "<bound method Function.signature of Function('cli', 8, 14)>",
-        "docstring": "doc-forge CLI: A tool for introspecting Python projects and generating\ndocumentation."
+        "signature": null,
+        "docstring": null
       },
       "build": {
         "name": "build",
         "kind": "function",
         "path": "docforge.cli.commands.build",
-        "signature": "<bound method Function.signature of Function('build', 16, 69)>",
-        "docstring": "Build documentation (MkDocs site or MCP resources)."
+        "signature": "<bound method Function.signature of Function('build', 18, 97)>",
+        "docstring": "Build documentation (MkDocs site or MCP resources).\n\nThis command orchestrates the full build process:\n1. Introspects the code (Griffe)\n2. Renders sources (MkDocs Markdown or MCP JSON)\n3. (MkDocs only) Generates config and runs the final site build.\n\nArgs:\n    mcp: Use the MCP documentation builder.\n    mkdocs: Use the MkDocs documentation builder.\n    module_is_source: Module is the source folder and to be treated as the root folder.\n    module: The dotted path of the module to the document.\n    project_name: Optional override for the project name.\n    site_name: (MkDocs) The site display name. Defaults to module name.\n    docs_dir: (MkDocs) Target directory for Markdown sources.\n    nav_file: (MkDocs) Path to the docforge.nav.yml specification.\n    template: (MkDocs) Optional custom mkdocs.yml template.\n    mkdocs_yml: (MkDocs) Target path for the generated mkdocs.yml.\n    out_dir: (MCP) Target directory for MCP JSON resources."
       },
       "serve": {
         "name": "serve",
         "kind": "function",
         "path": "docforge.cli.commands.serve",
-        "signature": "<bound method Function.signature of Function('serve', 71, 93)>",
-        "docstring": "Serve documentation."
+        "signature": "<bound method Function.signature of Function('serve', 100, 133)>",
+        "docstring": "Serve documentation (MkDocs or MCP).\n\nArgs:\n    mcp: Serve MCP resources via an MCP server.\n    mkdocs: Serve the MkDocs site using the built-in development server.\n    module: The dotted path of the module to serve.\n    mkdocs_yml: (MkDocs) Path to the mkdocs.yml configuration.\n    out_dir: (MCP) Path to the mcp_docs/ directory."
       },
       "tree": {
         "name": "tree",
         "kind": "function",
         "path": "docforge.cli.commands.tree",
-        "signature": "<bound method Function.signature of Function('tree', 95, 121)>",
-        "docstring": "Visualize the project structure."
+        "signature": "<bound method Function.signature of Function('tree', 136, 165)>",
+        "docstring": "Visualize the project structure in the terminal.\n\nArgs:\n    module: The module import path to recursively introspect.\n    project_name: Optional override for the project name shown at the root."
+      },
+      "Group": {
+        "name": "Group",
+        "kind": "alias",
+        "path": "docforge.cli.commands.Group",
+        "signature": "<bound method Alias.signature of Alias('Group', 'click.core.Group')>",
+        "docstring": null
+      },
+      "Any": {
+        "name": "Any",
+        "kind": "alias",
+        "path": "docforge.cli.commands.Any",
+        "signature": "<bound method Alias.signature of Alias('Any', 'typing.Any')>",
+        "docstring": null
       }
     }
   }

mcp_docs/modules/docforge.cli.json

@@ -2,27 +2,27 @@
   "module": "docforge.cli",
   "content": {
     "path": "docforge.cli",
-    "docstring": "# CLI Layer\n\nThe `docforge.cli` package provides the command-line interface for interacting\nwith doc-forge.\n\n## Available Commands\n\n- **tree**: Visualize the introspected project structure.\n- **generate**: Create Markdown source files from Python code.\n- **mkdocs**: Generate the primary `mkdocs.yml` configuration.\n- **build**: Build the final documentation site.\n- **serve**: Launch a local development server with live-reloading.",
+    "docstring": "# CLI Layer\n\nThe `docforge.cli` package provides the command-line interface for interacting\nwith doc-forge.\n\n## Available Commands\n\n- **build**: Build documentation (MkDocs site or MCP resources).\n- **serve**: Serve documentation (MkDocs or MCP).\n- **tree**: Visualize the introspected project structure.",
     "objects": {
       "main": {
         "name": "main",
         "kind": "module",
         "path": "docforge.cli.main",
         "signature": null,
-        "docstring": "Main entry point for the doc-forge CLI.",
+        "docstring": "Main entry point for the doc-forge CLI. This module delegates all command\nexecution to docforge.cli.commands.",
         "members": {
           "cli": {
             "name": "cli",
-            "kind": "function",
+            "kind": "attribute",
             "path": "docforge.cli.main.cli",
             "signature": "<bound method Alias.signature of Alias('cli', 'docforge.cli.commands.cli')>",
-            "docstring": "doc-forge CLI: A tool for introspecting Python projects and generating\ndocumentation."
+            "docstring": null
           },
           "main": {
             "name": "main",
             "kind": "function",
             "path": "docforge.cli.main.main",
-            "signature": "<bound method Function.signature of Function('main', 6, 10)>",
+            "signature": "<bound method Function.signature of Function('main', 7, 11)>",
             "docstring": "CLI Entry point. Boots the click application."
           }
         }
@@ -85,59 +85,59 @@
               }
             }
           },
-          "mkdocs_logic": {
-            "name": "mkdocs_logic",
+          "mkdocs_utils": {
+            "name": "mkdocs_utils",
             "kind": "module",
-            "path": "docforge.cli.commands.mkdocs_logic",
-            "signature": "<bound method Alias.signature of Alias('mkdocs_logic', 'docforge.cli.mkdocs.logic')>",
+            "path": "docforge.cli.commands.mkdocs_utils",
+            "signature": "<bound method Alias.signature of Alias('mkdocs_utils', 'docforge.cli.mkdocs_utils')>",
             "docstring": null,
             "members": {
               "Path": {
                 "name": "Path",
                 "kind": "alias",
-                "path": "docforge.cli.commands.mkdocs_logic.Path",
-                "signature": "<bound method Alias.signature of Alias('Path', 'docforge.cli.mkdocs.logic.Path')>",
+                "path": "docforge.cli.commands.mkdocs_utils.Path",
+                "signature": "<bound method Alias.signature of Alias('Path', 'docforge.cli.mkdocs_utils.Path')>",
                 "docstring": null
               },
               "resources": {
                 "name": "resources",
                 "kind": "alias",
-                "path": "docforge.cli.commands.mkdocs_logic.resources",
-                "signature": "<bound method Alias.signature of Alias('resources', 'docforge.cli.mkdocs.logic.resources')>",
+                "path": "docforge.cli.commands.mkdocs_utils.resources",
+                "signature": "<bound method Alias.signature of Alias('resources', 'docforge.cli.mkdocs_utils.resources')>",
                 "docstring": null
               },
               "click": {
                 "name": "click",
                 "kind": "alias",
-                "path": "docforge.cli.commands.mkdocs_logic.click",
-                "signature": "<bound method Alias.signature of Alias('click', 'docforge.cli.mkdocs.logic.click')>",
+                "path": "docforge.cli.commands.mkdocs_utils.click",
+                "signature": "<bound method Alias.signature of Alias('click', 'docforge.cli.mkdocs_utils.click')>",
                 "docstring": null
               },
               "yaml": {
                 "name": "yaml",
                 "kind": "alias",
-                "path": "docforge.cli.commands.mkdocs_logic.yaml",
-                "signature": "<bound method Alias.signature of Alias('yaml', 'docforge.cli.mkdocs.logic.yaml')>",
+                "path": "docforge.cli.commands.mkdocs_utils.yaml",
+                "signature": "<bound method Alias.signature of Alias('yaml', 'docforge.cli.mkdocs_utils.yaml')>",
                 "docstring": null
               },
               "GriffeLoader": {
                 "name": "GriffeLoader",
                 "kind": "class",
-                "path": "docforge.cli.commands.mkdocs_logic.GriffeLoader",
-                "signature": "<bound method Alias.signature of Alias('GriffeLoader', 'docforge.cli.mkdocs.logic.GriffeLoader')>",
+                "path": "docforge.cli.commands.mkdocs_utils.GriffeLoader",
+                "signature": "<bound method Alias.signature of Alias('GriffeLoader', 'docforge.cli.mkdocs_utils.GriffeLoader')>",
                 "docstring": "Loads Python modules and extracts documentation using the Griffe introspection engine.",
                 "members": {
                   "load_project": {
                     "name": "load_project",
                     "kind": "function",
-                    "path": "docforge.cli.commands.mkdocs_logic.GriffeLoader.load_project",
+                    "path": "docforge.cli.commands.mkdocs_utils.GriffeLoader.load_project",
                     "signature": "<bound method Alias.signature of Alias('load_project', 'docforge.loaders.griffe_loader.GriffeLoader.load_project')>",
                     "docstring": "Load multiple modules and combine them into a single Project models.\n\nArgs:\n    module_paths: A list of dotted paths to the modules to load.\n    project_name: Optional name for the project. Defaults to the first module name.\n    skip_import_errors: If True, modules that fail to import will be skipped.\n\nReturns:\n    A Project instance containing the loaded modules."
                   },
                   "load_module": {
                     "name": "load_module",
                     "kind": "function",
-                    "path": "docforge.cli.commands.mkdocs_logic.GriffeLoader.load_module",
+                    "path": "docforge.cli.commands.mkdocs_utils.GriffeLoader.load_module",
                     "signature": "<bound method Alias.signature of Alias('load_module', 'docforge.loaders.griffe_loader.GriffeLoader.load_module')>",
                     "docstring": "Load a single module and convert its introspection data into the docforge models.\n\nArgs:\n    path: The dotted path of the module to load.\n\nReturns:\n    A Module instance."
                   }
@@ -146,58 +146,58 @@
               "discover_module_paths": {
                 "name": "discover_module_paths",
                 "kind": "function",
-                "path": "docforge.cli.commands.mkdocs_logic.discover_module_paths",
-                "signature": "<bound method Alias.signature of Alias('discover_module_paths', 'docforge.cli.mkdocs.logic.discover_module_paths')>",
+                "path": "docforge.cli.commands.mkdocs_utils.discover_module_paths",
+                "signature": "<bound method Alias.signature of Alias('discover_module_paths', 'docforge.cli.mkdocs_utils.discover_module_paths')>",
                 "docstring": "Discover all Python modules under a package via filesystem traversal.\n\nRules:\n- Directory with __init__.py is treated as a package.\n- Any .py file is treated as a module.\n- All paths are converted to dotted module paths.\n\nArgs:\n    module_name: The name of the package to discover.\n    project_root: The root directory of the project. Defaults to current working directory.\n\nReturns:\n    A sorted list of dotted module paths."
               },
               "MkDocsRenderer": {
                 "name": "MkDocsRenderer",
                 "kind": "class",
-                "path": "docforge.cli.commands.mkdocs_logic.MkDocsRenderer",
-                "signature": "<bound method Alias.signature of Alias('MkDocsRenderer', 'docforge.cli.mkdocs.logic.MkDocsRenderer')>",
+                "path": "docforge.cli.commands.mkdocs_utils.MkDocsRenderer",
+                "signature": "<bound method Alias.signature of Alias('MkDocsRenderer', 'docforge.cli.mkdocs_utils.MkDocsRenderer')>",
                 "docstring": "Renderer that generates Markdown source files formatted for the MkDocs\n'mkdocstrings' plugin.",
                 "members": {
                   "name": {
                     "name": "name",
                     "kind": "attribute",
-                    "path": "docforge.cli.commands.mkdocs_logic.MkDocsRenderer.name",
+                    "path": "docforge.cli.commands.mkdocs_utils.MkDocsRenderer.name",
                     "signature": "<bound method Alias.signature of Alias('name', 'docforge.renderers.mkdocs_renderer.MkDocsRenderer.name')>",
                     "docstring": null
                   },
                   "generate_sources": {
                     "name": "generate_sources",
                     "kind": "function",
-                    "path": "docforge.cli.commands.mkdocs_logic.MkDocsRenderer.generate_sources",
+                    "path": "docforge.cli.commands.mkdocs_utils.MkDocsRenderer.generate_sources",
                     "signature": "<bound method Alias.signature of Alias('generate_sources', 'docforge.renderers.mkdocs_renderer.MkDocsRenderer.generate_sources')>",
-                    "docstring": "Produce a set of Markdown files in the output directory based on the\nprovided Project models.\n\nArgs:\n    project: The project models to render.\n    out_dir: Target directory for documentation files."
+                    "docstring": "Produce a set of Markdown files in the output directory based on the\nprovided Project models.\n\nArgs:\n    project: The project models to render.\n    out_dir: Target directory for documentation files.\n    module_is_source: Module is the source folder and to be treated as the root folder."
                   }
                 }
               },
               "load_nav_spec": {
                 "name": "load_nav_spec",
                 "kind": "function",
-                "path": "docforge.cli.commands.mkdocs_logic.load_nav_spec",
-                "signature": "<bound method Alias.signature of Alias('load_nav_spec', 'docforge.cli.mkdocs.logic.load_nav_spec')>",
+                "path": "docforge.cli.commands.mkdocs_utils.load_nav_spec",
+                "signature": "<bound method Alias.signature of Alias('load_nav_spec', 'docforge.cli.mkdocs_utils.load_nav_spec')>",
                 "docstring": "Utility function to load a NavSpec from a file.\n\nArgs:\n    path: Path to the navigation specification file.\n\nReturns:\n    A loaded NavSpec instance."
               },
               "resolve_nav": {
                 "name": "resolve_nav",
                 "kind": "function",
-                "path": "docforge.cli.commands.mkdocs_logic.resolve_nav",
-                "signature": "<bound method Alias.signature of Alias('resolve_nav', 'docforge.cli.mkdocs.logic.resolve_nav')>",
+                "path": "docforge.cli.commands.mkdocs_utils.resolve_nav",
+                "signature": "<bound method Alias.signature of Alias('resolve_nav', 'docforge.cli.mkdocs_utils.resolve_nav')>",
                 "docstring": "Create a ResolvedNav by processing a NavSpec against the filesystem.\nThis expands globs and validates the existence of referenced files.\n\nArgs:\n    spec: The navigation specification to resolve.\n    docs_root: The root directory for documentation files.\n\nReturns:\n    A ResolvedNav instance.\n\nRaises:\n    FileNotFoundError: If a pattern doesn't match any files or the docs_root doesn't exist."
               },
               "MkDocsNavEmitter": {
                 "name": "MkDocsNavEmitter",
                 "kind": "class",
-                "path": "docforge.cli.commands.mkdocs_logic.MkDocsNavEmitter",
-                "signature": "<bound method Alias.signature of Alias('MkDocsNavEmitter', 'docforge.cli.mkdocs.logic.MkDocsNavEmitter')>",
+                "path": "docforge.cli.commands.mkdocs_utils.MkDocsNavEmitter",
+                "signature": "<bound method Alias.signature of Alias('MkDocsNavEmitter', 'docforge.cli.mkdocs_utils.MkDocsNavEmitter')>",
                 "docstring": "Emitter responsible for transforming a ResolvedNav into an MkDocs-compatible\nnavigation structure.",
                 "members": {
                   "emit": {
                     "name": "emit",
                     "kind": "function",
-                    "path": "docforge.cli.commands.mkdocs_logic.MkDocsNavEmitter.emit",
+                    "path": "docforge.cli.commands.mkdocs_utils.MkDocsNavEmitter.emit",
                     "signature": "<bound method Alias.signature of Alias('emit', 'docforge.nav.mkdocs.MkDocsNavEmitter.emit')>",
                     "docstring": "Generate a list of navigation entries for mkdocs.yml.\n\nArgs:\n    nav: The resolved navigation data.\n\nReturns:\n    A list of dictionary mappings representing the MkDocs navigation."
                   }
@@ -206,72 +206,72 @@
               "generate_sources": {
                 "name": "generate_sources",
                 "kind": "function",
-                "path": "docforge.cli.commands.mkdocs_logic.generate_sources",
-                "signature": "<bound method Alias.signature of Alias('generate_sources', 'docforge.cli.mkdocs.logic.generate_sources')>",
-                "docstring": "Generate Markdown source files for the specified module."
+                "path": "docforge.cli.commands.mkdocs_utils.generate_sources",
+                "signature": "<bound method Alias.signature of Alias('generate_sources', 'docforge.cli.mkdocs_utils.generate_sources')>",
+                "docstring": "Generate Markdown source files for the specified module.\n\nArgs:\n    module: The dotted path of the primary module to document.\n    project_name: Optional override for the project name.\n    docs_dir: Directory where the generated Markdown files will be written.\n    module_is_source: Module is the source folder and to be treated as the root folder."
               },
               "generate_config": {
                 "name": "generate_config",
                 "kind": "function",
-                "path": "docforge.cli.commands.mkdocs_logic.generate_config",
-                "signature": "<bound method Alias.signature of Alias('generate_config', 'docforge.cli.mkdocs.logic.generate_config')>",
-                "docstring": "Generate an mkdocs.yml configuration file."
+                "path": "docforge.cli.commands.mkdocs_utils.generate_config",
+                "signature": "<bound method Alias.signature of Alias('generate_config', 'docforge.cli.mkdocs_utils.generate_config')>",
+                "docstring": "Generate an mkdocs.yml configuration file.\n\nArgs:\n    docs_dir: Path to the directory containing documentation Markdown files.\n    nav_file: Path to the docforge.nav.yml specification.\n    template: Optional path to an mkdocs.yml template (overrides built-in).\n    out: Path where the final mkdocs.yml will be written.\n    site_name: The display name for the documentation site."
               },
               "build": {
                 "name": "build",
                 "kind": "function",
-                "path": "docforge.cli.commands.mkdocs_logic.build",
-                "signature": "<bound method Alias.signature of Alias('build', 'docforge.cli.mkdocs.logic.build')>",
-                "docstring": "Build the documentation site using MkDocs."
+                "path": "docforge.cli.commands.mkdocs_utils.build",
+                "signature": "<bound method Alias.signature of Alias('build', 'docforge.cli.mkdocs_utils.build')>",
+                "docstring": "Build the documentation site using MkDocs.\n\nArgs:\n    mkdocs_yml: Path to the mkdocs.yml configuration file."
               },
               "serve": {
                 "name": "serve",
                 "kind": "function",
-                "path": "docforge.cli.commands.mkdocs_logic.serve",
-                "signature": "<bound method Alias.signature of Alias('serve', 'docforge.cli.mkdocs.logic.serve')>",
-                "docstring": "Serve the documentation site with live-reload using MkDocs."
+                "path": "docforge.cli.commands.mkdocs_utils.serve",
+                "signature": "<bound method Alias.signature of Alias('serve', 'docforge.cli.mkdocs_utils.serve')>",
+                "docstring": "Serve the documentation site with live-reload using MkDocs.\n\nArgs:\n    mkdocs_yml: Path to the mkdocs.yml configuration file."
               }
             }
           },
-          "mcp_logic": {
-            "name": "mcp_logic",
+          "mcp_utils": {
+            "name": "mcp_utils",
             "kind": "module",
-            "path": "docforge.cli.commands.mcp_logic",
-            "signature": "<bound method Alias.signature of Alias('mcp_logic', 'docforge.cli.mcp.logic')>",
+            "path": "docforge.cli.commands.mcp_utils",
+            "signature": "<bound method Alias.signature of Alias('mcp_utils', 'docforge.cli.mcp_utils')>",
             "docstring": null,
             "members": {
               "Path": {
                 "name": "Path",
                 "kind": "alias",
-                "path": "docforge.cli.commands.mcp_logic.Path",
-                "signature": "<bound method Alias.signature of Alias('Path', 'docforge.cli.mcp.logic.Path')>",
+                "path": "docforge.cli.commands.mcp_utils.Path",
+                "signature": "<bound method Alias.signature of Alias('Path', 'docforge.cli.mcp_utils.Path')>",
                 "docstring": null
               },
               "click": {
                 "name": "click",
                 "kind": "alias",
-                "path": "docforge.cli.commands.mcp_logic.click",
-                "signature": "<bound method Alias.signature of Alias('click', 'docforge.cli.mcp.logic.click')>",
+                "path": "docforge.cli.commands.mcp_utils.click",
+                "signature": "<bound method Alias.signature of Alias('click', 'docforge.cli.mcp_utils.click')>",
                 "docstring": null
               },
               "GriffeLoader": {
                 "name": "GriffeLoader",
                 "kind": "class",
-                "path": "docforge.cli.commands.mcp_logic.GriffeLoader",
-                "signature": "<bound method Alias.signature of Alias('GriffeLoader', 'docforge.cli.mcp.logic.GriffeLoader')>",
+                "path": "docforge.cli.commands.mcp_utils.GriffeLoader",
+                "signature": "<bound method Alias.signature of Alias('GriffeLoader', 'docforge.cli.mcp_utils.GriffeLoader')>",
                 "docstring": "Loads Python modules and extracts documentation using the Griffe introspection engine.",
                 "members": {
                   "load_project": {
                     "name": "load_project",
                     "kind": "function",
-                    "path": "docforge.cli.commands.mcp_logic.GriffeLoader.load_project",
+                    "path": "docforge.cli.commands.mcp_utils.GriffeLoader.load_project",
                     "signature": "<bound method Alias.signature of Alias('load_project', 'docforge.loaders.griffe_loader.GriffeLoader.load_project')>",
                     "docstring": "Load multiple modules and combine them into a single Project models.\n\nArgs:\n    module_paths: A list of dotted paths to the modules to load.\n    project_name: Optional name for the project. Defaults to the first module name.\n    skip_import_errors: If True, modules that fail to import will be skipped.\n\nReturns:\n    A Project instance containing the loaded modules."
                   },
                   "load_module": {
                     "name": "load_module",
                     "kind": "function",
-                    "path": "docforge.cli.commands.mcp_logic.GriffeLoader.load_module",
+                    "path": "docforge.cli.commands.mcp_utils.GriffeLoader.load_module",
                     "signature": "<bound method Alias.signature of Alias('load_module', 'docforge.loaders.griffe_loader.GriffeLoader.load_module')>",
                     "docstring": "Load a single module and convert its introspection data into the docforge models.\n\nArgs:\n    path: The dotted path of the module to load.\n\nReturns:\n    A Module instance."
                   }
@@ -280,58 +280,58 @@
               "discover_module_paths": {
                 "name": "discover_module_paths",
                 "kind": "function",
-                "path": "docforge.cli.commands.mcp_logic.discover_module_paths",
-                "signature": "<bound method Alias.signature of Alias('discover_module_paths', 'docforge.cli.mcp.logic.discover_module_paths')>",
+                "path": "docforge.cli.commands.mcp_utils.discover_module_paths",
+                "signature": "<bound method Alias.signature of Alias('discover_module_paths', 'docforge.cli.mcp_utils.discover_module_paths')>",
                 "docstring": "Discover all Python modules under a package via filesystem traversal.\n\nRules:\n- Directory with __init__.py is treated as a package.\n- Any .py file is treated as a module.\n- All paths are converted to dotted module paths.\n\nArgs:\n    module_name: The name of the package to discover.\n    project_root: The root directory of the project. Defaults to current working directory.\n\nReturns:\n    A sorted list of dotted module paths."
               },
               "MCPRenderer": {
                 "name": "MCPRenderer",
                 "kind": "class",
-                "path": "docforge.cli.commands.mcp_logic.MCPRenderer",
-                "signature": "<bound method Alias.signature of Alias('MCPRenderer', 'docforge.cli.mcp.logic.MCPRenderer')>",
+                "path": "docforge.cli.commands.mcp_utils.MCPRenderer",
+                "signature": "<bound method Alias.signature of Alias('MCPRenderer', 'docforge.cli.mcp_utils.MCPRenderer')>",
                 "docstring": "Renderer that emits MCP-native JSON resources from docforge models.",
                 "members": {
                   "name": {
                     "name": "name",
                     "kind": "attribute",
-                    "path": "docforge.cli.commands.mcp_logic.MCPRenderer.name",
+                    "path": "docforge.cli.commands.mcp_utils.MCPRenderer.name",
                     "signature": "<bound method Alias.signature of Alias('name', 'docforge.renderers.mcp_renderer.MCPRenderer.name')>",
                     "docstring": null
                   },
                   "generate_sources": {
                     "name": "generate_sources",
                     "kind": "function",
-                    "path": "docforge.cli.commands.mcp_logic.MCPRenderer.generate_sources",
+                    "path": "docforge.cli.commands.mcp_utils.MCPRenderer.generate_sources",
                     "signature": "<bound method Alias.signature of Alias('generate_sources', 'docforge.renderers.mcp_renderer.MCPRenderer.generate_sources')>",
-                    "docstring": "Generate MCP-compatible JSON resources and navigation for the project."
+                    "docstring": "Generate MCP-compatible JSON resources and navigation for the project.\n\nArgs:\n    project: The project model to render.\n    out_dir: Target directory for the generated JSON files."
                   }
                 }
               },
               "MCPServer": {
                 "name": "MCPServer",
                 "kind": "class",
-                "path": "docforge.cli.commands.mcp_logic.MCPServer",
-                "signature": "<bound method Alias.signature of Alias('MCPServer', 'docforge.cli.mcp.logic.MCPServer')>",
+                "path": "docforge.cli.commands.mcp_utils.MCPServer",
+                "signature": "<bound method Alias.signature of Alias('MCPServer', 'docforge.cli.mcp_utils.MCPServer')>",
                 "docstring": "MCP server for serving a pre-built MCP documentation bundle.",
                 "members": {
                   "mcp_root": {
                     "name": "mcp_root",
                     "kind": "attribute",
-                    "path": "docforge.cli.commands.mcp_logic.MCPServer.mcp_root",
+                    "path": "docforge.cli.commands.mcp_utils.MCPServer.mcp_root",
                     "signature": "<bound method Alias.signature of Alias('mcp_root', 'docforge.servers.mcp_server.MCPServer.mcp_root')>",
                     "docstring": null
                   },
                   "app": {
                     "name": "app",
                     "kind": "attribute",
-                    "path": "docforge.cli.commands.mcp_logic.MCPServer.app",
+                    "path": "docforge.cli.commands.mcp_utils.MCPServer.app",
                     "signature": "<bound method Alias.signature of Alias('app', 'docforge.servers.mcp_server.MCPServer.app')>",
                     "docstring": null
                   },
                   "run": {
                     "name": "run",
                     "kind": "function",
-                    "path": "docforge.cli.commands.mcp_logic.MCPServer.run",
+                    "path": "docforge.cli.commands.mcp_utils.MCPServer.run",
                     "signature": "<bound method Alias.signature of Alias('run', 'docforge.servers.mcp_server.MCPServer.run')>",
                     "docstring": "Start the MCP server.\n\nArgs:\n    transport: MCP transport (default: streamable-http)"
                   }
@@ -340,332 +340,328 @@
               "generate_resources": {
                 "name": "generate_resources",
                 "kind": "function",
-                "path": "docforge.cli.commands.mcp_logic.generate_resources",
-                "signature": "<bound method Alias.signature of Alias('generate_resources', 'docforge.cli.mcp.logic.generate_resources')>",
-                "docstring": "Generate MCP-compatible documentation resources."
+                "path": "docforge.cli.commands.mcp_utils.generate_resources",
+                "signature": "<bound method Alias.signature of Alias('generate_resources', 'docforge.cli.mcp_utils.generate_resources')>",
+                "docstring": "Generate MCP-compatible documentation resources.\n\nArgs:\n    module: The dotted path of the primary module to document.\n    project_name: Optional override for the project name.\n    out_dir: Directory where the MCP JSON resources and nav will be written."
               },
               "serve": {
                 "name": "serve",
                 "kind": "function",
-                "path": "docforge.cli.commands.mcp_logic.serve",
-                "signature": "<bound method Alias.signature of Alias('serve', 'docforge.cli.mcp.logic.serve')>",
-                "docstring": "Serve MCP documentation."
+                "path": "docforge.cli.commands.mcp_utils.serve",
+                "signature": "<bound method Alias.signature of Alias('serve', 'docforge.cli.mcp_utils.serve')>",
+                "docstring": "Serve MCP documentation from a pre-built bundle.\n\nArgs:\n    module: The dotted path of the primary module to serve.\n    mcp_root: Path to the directory containing index.json, nav.json, and modules/."
               }
             }
           },
           "cli": {
             "name": "cli",
-            "kind": "function",
+            "kind": "attribute",
             "path": "docforge.cli.commands.cli",
-            "signature": "<bound method Function.signature of Function('cli', 8, 14)>",
-            "docstring": "doc-forge CLI: A tool for introspecting Python projects and generating\ndocumentation."
+            "signature": null,
+            "docstring": null
           },
           "build": {
             "name": "build",
             "kind": "function",
             "path": "docforge.cli.commands.build",
-            "signature": "<bound method Function.signature of Function('build', 16, 69)>",
-            "docstring": "Build documentation (MkDocs site or MCP resources)."
+            "signature": "<bound method Function.signature of Function('build', 18, 97)>",
+            "docstring": "Build documentation (MkDocs site or MCP resources).\n\nThis command orchestrates the full build process:\n1. Introspects the code (Griffe)\n2. Renders sources (MkDocs Markdown or MCP JSON)\n3. (MkDocs only) Generates config and runs the final site build.\n\nArgs:\n    mcp: Use the MCP documentation builder.\n    mkdocs: Use the MkDocs documentation builder.\n    module_is_source: Module is the source folder and to be treated as the root folder.\n    module: The dotted path of the module to the document.\n    project_name: Optional override for the project name.\n    site_name: (MkDocs) The site display name. Defaults to module name.\n    docs_dir: (MkDocs) Target directory for Markdown sources.\n    nav_file: (MkDocs) Path to the docforge.nav.yml specification.\n    template: (MkDocs) Optional custom mkdocs.yml template.\n    mkdocs_yml: (MkDocs) Target path for the generated mkdocs.yml.\n    out_dir: (MCP) Target directory for MCP JSON resources."
           },
           "serve": {
             "name": "serve",
             "kind": "function",
             "path": "docforge.cli.commands.serve",
-            "signature": "<bound method Function.signature of Function('serve', 71, 93)>",
-            "docstring": "Serve documentation."
+            "signature": "<bound method Function.signature of Function('serve', 100, 133)>",
+            "docstring": "Serve documentation (MkDocs or MCP).\n\nArgs:\n    mcp: Serve MCP resources via an MCP server.\n    mkdocs: Serve the MkDocs site using the built-in development server.\n    module: The dotted path of the module to serve.\n    mkdocs_yml: (MkDocs) Path to the mkdocs.yml configuration.\n    out_dir: (MCP) Path to the mcp_docs/ directory."
           },
           "tree": {
             "name": "tree",
             "kind": "function",
             "path": "docforge.cli.commands.tree",
-            "signature": "<bound method Function.signature of Function('tree', 95, 121)>",
-            "docstring": "Visualize the project structure."
+            "signature": "<bound method Function.signature of Function('tree', 136, 165)>",
+            "docstring": "Visualize the project structure in the terminal.\n\nArgs:\n    module: The module import path to recursively introspect.\n    project_name: Optional override for the project name shown at the root."
+          },
+          "Group": {
+            "name": "Group",
+            "kind": "alias",
+            "path": "docforge.cli.commands.Group",
+            "signature": "<bound method Alias.signature of Alias('Group', 'click.core.Group')>",
+            "docstring": null
+          },
+          "Any": {
+            "name": "Any",
+            "kind": "alias",
+            "path": "docforge.cli.commands.Any",
+            "signature": "<bound method Alias.signature of Alias('Any', 'typing.Any')>",
+            "docstring": null
           }
         }
       },
-      "mcp": {
-        "name": "mcp",
+      "mcp_utils": {
+        "name": "mcp_utils",
         "kind": "module",
-        "path": "docforge.cli.mcp",
+        "path": "docforge.cli.mcp_utils",
         "signature": null,
         "docstring": null,
         "members": {
-          "logic": {
-            "name": "logic",
-            "kind": "module",
-            "path": "docforge.cli.mcp.logic",
-            "signature": null,
-            "docstring": null,
+          "Path": {
+            "name": "Path",
+            "kind": "alias",
+            "path": "docforge.cli.mcp_utils.Path",
+            "signature": "<bound method Alias.signature of Alias('Path', 'pathlib.Path')>",
+            "docstring": null
+          },
+          "click": {
+            "name": "click",
+            "kind": "alias",
+            "path": "docforge.cli.mcp_utils.click",
+            "signature": "<bound method Alias.signature of Alias('click', 'click')>",
+            "docstring": null
+          },
+          "GriffeLoader": {
+            "name": "GriffeLoader",
+            "kind": "class",
+            "path": "docforge.cli.mcp_utils.GriffeLoader",
+            "signature": "<bound method Alias.signature of Alias('GriffeLoader', 'docforge.loaders.GriffeLoader')>",
+            "docstring": "Loads Python modules and extracts documentation using the Griffe introspection engine.",
             "members": {
-              "Path": {
-                "name": "Path",
-                "kind": "alias",
-                "path": "docforge.cli.mcp.logic.Path",
-                "signature": "<bound method Alias.signature of Alias('Path', 'pathlib.Path')>",
-                "docstring": null
-              },
-              "click": {
-                "name": "click",
-                "kind": "alias",
-                "path": "docforge.cli.mcp.logic.click",
-                "signature": "<bound method Alias.signature of Alias('click', 'click')>",
-                "docstring": null
-              },
-              "GriffeLoader": {
-                "name": "GriffeLoader",
-                "kind": "class",
-                "path": "docforge.cli.mcp.logic.GriffeLoader",
-                "signature": "<bound method Alias.signature of Alias('GriffeLoader', 'docforge.loaders.GriffeLoader')>",
-                "docstring": "Loads Python modules and extracts documentation using the Griffe introspection engine.",
-                "members": {
-                  "load_project": {
-                    "name": "load_project",
-                    "kind": "function",
-                    "path": "docforge.cli.mcp.logic.GriffeLoader.load_project",
-                    "signature": "<bound method Alias.signature of Alias('load_project', 'docforge.loaders.griffe_loader.GriffeLoader.load_project')>",
-                    "docstring": "Load multiple modules and combine them into a single Project models.\n\nArgs:\n    module_paths: A list of dotted paths to the modules to load.\n    project_name: Optional name for the project. Defaults to the first module name.\n    skip_import_errors: If True, modules that fail to import will be skipped.\n\nReturns:\n    A Project instance containing the loaded modules."
-                  },
-                  "load_module": {
-                    "name": "load_module",
-                    "kind": "function",
-                    "path": "docforge.cli.mcp.logic.GriffeLoader.load_module",
-                    "signature": "<bound method Alias.signature of Alias('load_module', 'docforge.loaders.griffe_loader.GriffeLoader.load_module')>",
-                    "docstring": "Load a single module and convert its introspection data into the docforge models.\n\nArgs:\n    path: The dotted path of the module to load.\n\nReturns:\n    A Module instance."
-                  }
-                }
-              },
-              "discover_module_paths": {
-                "name": "discover_module_paths",
+              "load_project": {
+                "name": "load_project",
                 "kind": "function",
-                "path": "docforge.cli.mcp.logic.discover_module_paths",
-                "signature": "<bound method Alias.signature of Alias('discover_module_paths', 'docforge.loaders.discover_module_paths')>",
-                "docstring": "Discover all Python modules under a package via filesystem traversal.\n\nRules:\n- Directory with __init__.py is treated as a package.\n- Any .py file is treated as a module.\n- All paths are converted to dotted module paths.\n\nArgs:\n    module_name: The name of the package to discover.\n    project_root: The root directory of the project. Defaults to current working directory.\n\nReturns:\n    A sorted list of dotted module paths."
+                "path": "docforge.cli.mcp_utils.GriffeLoader.load_project",
+                "signature": "<bound method Alias.signature of Alias('load_project', 'docforge.loaders.griffe_loader.GriffeLoader.load_project')>",
+                "docstring": "Load multiple modules and combine them into a single Project models.\n\nArgs:\n    module_paths: A list of dotted paths to the modules to load.\n    project_name: Optional name for the project. Defaults to the first module name.\n    skip_import_errors: If True, modules that fail to import will be skipped.\n\nReturns:\n    A Project instance containing the loaded modules."
               },
-              "MCPRenderer": {
-                "name": "MCPRenderer",
-                "kind": "class",
-                "path": "docforge.cli.mcp.logic.MCPRenderer",
-                "signature": "<bound method Alias.signature of Alias('MCPRenderer', 'docforge.renderers.MCPRenderer')>",
-                "docstring": "Renderer that emits MCP-native JSON resources from docforge models.",
-                "members": {
-                  "name": {
-                    "name": "name",
-                    "kind": "attribute",
-                    "path": "docforge.cli.mcp.logic.MCPRenderer.name",
-                    "signature": "<bound method Alias.signature of Alias('name', 'docforge.renderers.mcp_renderer.MCPRenderer.name')>",
-                    "docstring": null
-                  },
-                  "generate_sources": {
-                    "name": "generate_sources",
-                    "kind": "function",
-                    "path": "docforge.cli.mcp.logic.MCPRenderer.generate_sources",
-                    "signature": "<bound method Alias.signature of Alias('generate_sources', 'docforge.renderers.mcp_renderer.MCPRenderer.generate_sources')>",
-                    "docstring": "Generate MCP-compatible JSON resources and navigation for the project."
-                  }
-                }
-              },
-              "MCPServer": {
-                "name": "MCPServer",
-                "kind": "class",
-                "path": "docforge.cli.mcp.logic.MCPServer",
-                "signature": "<bound method Alias.signature of Alias('MCPServer', 'docforge.servers.MCPServer')>",
-                "docstring": "MCP server for serving a pre-built MCP documentation bundle.",
-                "members": {
-                  "mcp_root": {
-                    "name": "mcp_root",
-                    "kind": "attribute",
-                    "path": "docforge.cli.mcp.logic.MCPServer.mcp_root",
-                    "signature": "<bound method Alias.signature of Alias('mcp_root', 'docforge.servers.mcp_server.MCPServer.mcp_root')>",
-                    "docstring": null
-                  },
-                  "app": {
-                    "name": "app",
-                    "kind": "attribute",
-                    "path": "docforge.cli.mcp.logic.MCPServer.app",
-                    "signature": "<bound method Alias.signature of Alias('app', 'docforge.servers.mcp_server.MCPServer.app')>",
-                    "docstring": null
-                  },
-                  "run": {
-                    "name": "run",
-                    "kind": "function",
-                    "path": "docforge.cli.mcp.logic.MCPServer.run",
-                    "signature": "<bound method Alias.signature of Alias('run', 'docforge.servers.mcp_server.MCPServer.run')>",
-                    "docstring": "Start the MCP server.\n\nArgs:\n    transport: MCP transport (default: streamable-http)"
-                  }
-                }
-              },
-              "generate_resources": {
-                "name": "generate_resources",
+              "load_module": {
+                "name": "load_module",
                 "kind": "function",
-                "path": "docforge.cli.mcp.logic.generate_resources",
-                "signature": "<bound method Function.signature of Function('generate_resources', 7, 16)>",
-                "docstring": "Generate MCP-compatible documentation resources."
-              },
-              "serve": {
-                "name": "serve",
-                "kind": "function",
-                "path": "docforge.cli.mcp.logic.serve",
-                "signature": "<bound method Function.signature of Function('serve', 18, 39)>",
-                "docstring": "Serve MCP documentation."
+                "path": "docforge.cli.mcp_utils.GriffeLoader.load_module",
+                "signature": "<bound method Alias.signature of Alias('load_module', 'docforge.loaders.griffe_loader.GriffeLoader.load_module')>",
+                "docstring": "Load a single module and convert its introspection data into the docforge models.\n\nArgs:\n    path: The dotted path of the module to load.\n\nReturns:\n    A Module instance."
               }
             }
-          }
-        }
-      },
-      "mkdocs": {
-        "name": "mkdocs",
-        "kind": "module",
-        "path": "docforge.cli.mkdocs",
-        "signature": null,
-        "docstring": null,
-        "members": {
-          "logic": {
-            "name": "logic",
-            "kind": "module",
-            "path": "docforge.cli.mkdocs.logic",
-            "signature": null,
-            "docstring": null,
+          },
+          "discover_module_paths": {
+            "name": "discover_module_paths",
+            "kind": "function",
+            "path": "docforge.cli.mcp_utils.discover_module_paths",
+            "signature": "<bound method Alias.signature of Alias('discover_module_paths', 'docforge.loaders.discover_module_paths')>",
+            "docstring": "Discover all Python modules under a package via filesystem traversal.\n\nRules:\n- Directory with __init__.py is treated as a package.\n- Any .py file is treated as a module.\n- All paths are converted to dotted module paths.\n\nArgs:\n    module_name: The name of the package to discover.\n    project_root: The root directory of the project. Defaults to current working directory.\n\nReturns:\n    A sorted list of dotted module paths."
+          },
+          "MCPRenderer": {
+            "name": "MCPRenderer",
+            "kind": "class",
+            "path": "docforge.cli.mcp_utils.MCPRenderer",
+            "signature": "<bound method Alias.signature of Alias('MCPRenderer', 'docforge.renderers.MCPRenderer')>",
+            "docstring": "Renderer that emits MCP-native JSON resources from docforge models.",
             "members": {
-              "Path": {
-                "name": "Path",
-                "kind": "alias",
-                "path": "docforge.cli.mkdocs.logic.Path",
-                "signature": "<bound method Alias.signature of Alias('Path', 'pathlib.Path')>",
+              "name": {
+                "name": "name",
+                "kind": "attribute",
+                "path": "docforge.cli.mcp_utils.MCPRenderer.name",
+                "signature": "<bound method Alias.signature of Alias('name', 'docforge.renderers.mcp_renderer.MCPRenderer.name')>",
                 "docstring": null
               },
-              "resources": {
-                "name": "resources",
-                "kind": "alias",
-                "path": "docforge.cli.mkdocs.logic.resources",
-                "signature": "<bound method Alias.signature of Alias('resources', 'importlib.resources')>",
-                "docstring": null
-              },
-              "click": {
-                "name": "click",
-                "kind": "alias",
-                "path": "docforge.cli.mkdocs.logic.click",
-                "signature": "<bound method Alias.signature of Alias('click', 'click')>",
-                "docstring": null
-              },
-              "yaml": {
-                "name": "yaml",
-                "kind": "alias",
-                "path": "docforge.cli.mkdocs.logic.yaml",
-                "signature": "<bound method Alias.signature of Alias('yaml', 'yaml')>",
-                "docstring": null
-              },
-              "GriffeLoader": {
-                "name": "GriffeLoader",
-                "kind": "class",
-                "path": "docforge.cli.mkdocs.logic.GriffeLoader",
-                "signature": "<bound method Alias.signature of Alias('GriffeLoader', 'docforge.loaders.GriffeLoader')>",
-                "docstring": "Loads Python modules and extracts documentation using the Griffe introspection engine.",
-                "members": {
-                  "load_project": {
-                    "name": "load_project",
-                    "kind": "function",
-                    "path": "docforge.cli.mkdocs.logic.GriffeLoader.load_project",
-                    "signature": "<bound method Alias.signature of Alias('load_project', 'docforge.loaders.griffe_loader.GriffeLoader.load_project')>",
-                    "docstring": "Load multiple modules and combine them into a single Project models.\n\nArgs:\n    module_paths: A list of dotted paths to the modules to load.\n    project_name: Optional name for the project. Defaults to the first module name.\n    skip_import_errors: If True, modules that fail to import will be skipped.\n\nReturns:\n    A Project instance containing the loaded modules."
-                  },
-                  "load_module": {
-                    "name": "load_module",
-                    "kind": "function",
-                    "path": "docforge.cli.mkdocs.logic.GriffeLoader.load_module",
-                    "signature": "<bound method Alias.signature of Alias('load_module', 'docforge.loaders.griffe_loader.GriffeLoader.load_module')>",
-                    "docstring": "Load a single module and convert its introspection data into the docforge models.\n\nArgs:\n    path: The dotted path of the module to load.\n\nReturns:\n    A Module instance."
-                  }
-                }
-              },
-              "discover_module_paths": {
-                "name": "discover_module_paths",
-                "kind": "function",
-                "path": "docforge.cli.mkdocs.logic.discover_module_paths",
-                "signature": "<bound method Alias.signature of Alias('discover_module_paths', 'docforge.loaders.discover_module_paths')>",
-                "docstring": "Discover all Python modules under a package via filesystem traversal.\n\nRules:\n- Directory with __init__.py is treated as a package.\n- Any .py file is treated as a module.\n- All paths are converted to dotted module paths.\n\nArgs:\n    module_name: The name of the package to discover.\n    project_root: The root directory of the project. Defaults to current working directory.\n\nReturns:\n    A sorted list of dotted module paths."
-              },
-              "MkDocsRenderer": {
-                "name": "MkDocsRenderer",
-                "kind": "class",
-                "path": "docforge.cli.mkdocs.logic.MkDocsRenderer",
-                "signature": "<bound method Alias.signature of Alias('MkDocsRenderer', 'docforge.renderers.MkDocsRenderer')>",
-                "docstring": "Renderer that generates Markdown source files formatted for the MkDocs\n'mkdocstrings' plugin.",
-                "members": {
-                  "name": {
-                    "name": "name",
-                    "kind": "attribute",
-                    "path": "docforge.cli.mkdocs.logic.MkDocsRenderer.name",
-                    "signature": "<bound method Alias.signature of Alias('name', 'docforge.renderers.mkdocs_renderer.MkDocsRenderer.name')>",
-                    "docstring": null
-                  },
-                  "generate_sources": {
-                    "name": "generate_sources",
-                    "kind": "function",
-                    "path": "docforge.cli.mkdocs.logic.MkDocsRenderer.generate_sources",
-                    "signature": "<bound method Alias.signature of Alias('generate_sources', 'docforge.renderers.mkdocs_renderer.MkDocsRenderer.generate_sources')>",
-                    "docstring": "Produce a set of Markdown files in the output directory based on the\nprovided Project models.\n\nArgs:\n    project: The project models to render.\n    out_dir: Target directory for documentation files."
-                  }
-                }
-              },
-              "load_nav_spec": {
-                "name": "load_nav_spec",
-                "kind": "function",
-                "path": "docforge.cli.mkdocs.logic.load_nav_spec",
-                "signature": "<bound method Alias.signature of Alias('load_nav_spec', 'docforge.nav.load_nav_spec')>",
-                "docstring": "Utility function to load a NavSpec from a file.\n\nArgs:\n    path: Path to the navigation specification file.\n\nReturns:\n    A loaded NavSpec instance."
-              },
-              "resolve_nav": {
-                "name": "resolve_nav",
-                "kind": "function",
-                "path": "docforge.cli.mkdocs.logic.resolve_nav",
-                "signature": "<bound method Alias.signature of Alias('resolve_nav', 'docforge.nav.resolve_nav')>",
-                "docstring": "Create a ResolvedNav by processing a NavSpec against the filesystem.\nThis expands globs and validates the existence of referenced files.\n\nArgs:\n    spec: The navigation specification to resolve.\n    docs_root: The root directory for documentation files.\n\nReturns:\n    A ResolvedNav instance.\n\nRaises:\n    FileNotFoundError: If a pattern doesn't match any files or the docs_root doesn't exist."
-              },
-              "MkDocsNavEmitter": {
-                "name": "MkDocsNavEmitter",
-                "kind": "class",
-                "path": "docforge.cli.mkdocs.logic.MkDocsNavEmitter",
-                "signature": "<bound method Alias.signature of Alias('MkDocsNavEmitter', 'docforge.nav.MkDocsNavEmitter')>",
-                "docstring": "Emitter responsible for transforming a ResolvedNav into an MkDocs-compatible\nnavigation structure.",
-                "members": {
-                  "emit": {
-                    "name": "emit",
-                    "kind": "function",
-                    "path": "docforge.cli.mkdocs.logic.MkDocsNavEmitter.emit",
-                    "signature": "<bound method Alias.signature of Alias('emit', 'docforge.nav.mkdocs.MkDocsNavEmitter.emit')>",
-                    "docstring": "Generate a list of navigation entries for mkdocs.yml.\n\nArgs:\n    nav: The resolved navigation data.\n\nReturns:\n    A list of dictionary mappings representing the MkDocs navigation."
-                  }
-                }
-              },
               "generate_sources": {
                 "name": "generate_sources",
                 "kind": "function",
-                "path": "docforge.cli.mkdocs.logic.generate_sources",
-                "signature": "<bound method Function.signature of Function('generate_sources', 9, 18)>",
-                "docstring": "Generate Markdown source files for the specified module."
-              },
-              "generate_config": {
-                "name": "generate_config",
-                "kind": "function",
-                "path": "docforge.cli.mkdocs.logic.generate_config",
-                "signature": "<bound method Function.signature of Function('generate_config', 20, 47)>",
-                "docstring": "Generate an mkdocs.yml configuration file."
-              },
-              "build": {
-                "name": "build",
-                "kind": "function",
-                "path": "docforge.cli.mkdocs.logic.build",
-                "signature": "<bound method Function.signature of Function('build', 49, 59)>",
-                "docstring": "Build the documentation site using MkDocs."
-              },
-              "serve": {
-                "name": "serve",
-                "kind": "function",
-                "path": "docforge.cli.mkdocs.logic.serve",
-                "signature": "<bound method Function.signature of Function('serve', 61, 69)>",
-                "docstring": "Serve the documentation site with live-reload using MkDocs."
+                "path": "docforge.cli.mcp_utils.MCPRenderer.generate_sources",
+                "signature": "<bound method Alias.signature of Alias('generate_sources', 'docforge.renderers.mcp_renderer.MCPRenderer.generate_sources')>",
+                "docstring": "Generate MCP-compatible JSON resources and navigation for the project.\n\nArgs:\n    project: The project model to render.\n    out_dir: Target directory for the generated JSON files."
               }
             }
+          },
+          "MCPServer": {
+            "name": "MCPServer",
+            "kind": "class",
+            "path": "docforge.cli.mcp_utils.MCPServer",
+            "signature": "<bound method Alias.signature of Alias('MCPServer', 'docforge.servers.MCPServer')>",
+            "docstring": "MCP server for serving a pre-built MCP documentation bundle.",
+            "members": {
+              "mcp_root": {
+                "name": "mcp_root",
+                "kind": "attribute",
+                "path": "docforge.cli.mcp_utils.MCPServer.mcp_root",
+                "signature": "<bound method Alias.signature of Alias('mcp_root', 'docforge.servers.mcp_server.MCPServer.mcp_root')>",
+                "docstring": null
+              },
+              "app": {
+                "name": "app",
+                "kind": "attribute",
+                "path": "docforge.cli.mcp_utils.MCPServer.app",
+                "signature": "<bound method Alias.signature of Alias('app', 'docforge.servers.mcp_server.MCPServer.app')>",
+                "docstring": null
+              },
+              "run": {
+                "name": "run",
+                "kind": "function",
+                "path": "docforge.cli.mcp_utils.MCPServer.run",
+                "signature": "<bound method Alias.signature of Alias('run', 'docforge.servers.mcp_server.MCPServer.run')>",
+                "docstring": "Start the MCP server.\n\nArgs:\n    transport: MCP transport (default: streamable-http)"
+              }
+            }
+          },
+          "generate_resources": {
+            "name": "generate_resources",
+            "kind": "function",
+            "path": "docforge.cli.mcp_utils.generate_resources",
+            "signature": "<bound method Function.signature of Function('generate_resources', 7, 21)>",
+            "docstring": "Generate MCP-compatible documentation resources.\n\nArgs:\n    module: The dotted path of the primary module to document.\n    project_name: Optional override for the project name.\n    out_dir: Directory where the MCP JSON resources and nav will be written."
+          },
+          "serve": {
+            "name": "serve",
+            "kind": "function",
+            "path": "docforge.cli.mcp_utils.serve",
+            "signature": "<bound method Function.signature of Function('serve', 23, 48)>",
+            "docstring": "Serve MCP documentation from a pre-built bundle.\n\nArgs:\n    module: The dotted path of the primary module to serve.\n    mcp_root: Path to the directory containing index.json, nav.json, and modules/."
+          }
+        }
+      },
+      "mkdocs_utils": {
+        "name": "mkdocs_utils",
+        "kind": "module",
+        "path": "docforge.cli.mkdocs_utils",
+        "signature": null,
+        "docstring": null,
+        "members": {
+          "Path": {
+            "name": "Path",
+            "kind": "alias",
+            "path": "docforge.cli.mkdocs_utils.Path",
+            "signature": "<bound method Alias.signature of Alias('Path', 'pathlib.Path')>",
+            "docstring": null
+          },
+          "resources": {
+            "name": "resources",
+            "kind": "alias",
+            "path": "docforge.cli.mkdocs_utils.resources",
+            "signature": "<bound method Alias.signature of Alias('resources', 'importlib.resources')>",
+            "docstring": null
+          },
+          "click": {
+            "name": "click",
+            "kind": "alias",
+            "path": "docforge.cli.mkdocs_utils.click",
+            "signature": "<bound method Alias.signature of Alias('click', 'click')>",
+            "docstring": null
+          },
+          "yaml": {
+            "name": "yaml",
+            "kind": "alias",
+            "path": "docforge.cli.mkdocs_utils.yaml",
+            "signature": "<bound method Alias.signature of Alias('yaml', 'yaml')>",
+            "docstring": null
+          },
+          "GriffeLoader": {
+            "name": "GriffeLoader",
+            "kind": "class",
+            "path": "docforge.cli.mkdocs_utils.GriffeLoader",
+            "signature": "<bound method Alias.signature of Alias('GriffeLoader', 'docforge.loaders.GriffeLoader')>",
+            "docstring": "Loads Python modules and extracts documentation using the Griffe introspection engine.",
+            "members": {
+              "load_project": {
+                "name": "load_project",
+                "kind": "function",
+                "path": "docforge.cli.mkdocs_utils.GriffeLoader.load_project",
+                "signature": "<bound method Alias.signature of Alias('load_project', 'docforge.loaders.griffe_loader.GriffeLoader.load_project')>",
+                "docstring": "Load multiple modules and combine them into a single Project models.\n\nArgs:\n    module_paths: A list of dotted paths to the modules to load.\n    project_name: Optional name for the project. Defaults to the first module name.\n    skip_import_errors: If True, modules that fail to import will be skipped.\n\nReturns:\n    A Project instance containing the loaded modules."
+              },
+              "load_module": {
+                "name": "load_module",
+                "kind": "function",
+                "path": "docforge.cli.mkdocs_utils.GriffeLoader.load_module",
+                "signature": "<bound method Alias.signature of Alias('load_module', 'docforge.loaders.griffe_loader.GriffeLoader.load_module')>",
+                "docstring": "Load a single module and convert its introspection data into the docforge models.\n\nArgs:\n    path: The dotted path of the module to load.\n\nReturns:\n    A Module instance."
+              }
+            }
+          },
+          "discover_module_paths": {
+            "name": "discover_module_paths",
+            "kind": "function",
+            "path": "docforge.cli.mkdocs_utils.discover_module_paths",
+            "signature": "<bound method Alias.signature of Alias('discover_module_paths', 'docforge.loaders.discover_module_paths')>",
+            "docstring": "Discover all Python modules under a package via filesystem traversal.\n\nRules:\n- Directory with __init__.py is treated as a package.\n- Any .py file is treated as a module.\n- All paths are converted to dotted module paths.\n\nArgs:\n    module_name: The name of the package to discover.\n    project_root: The root directory of the project. Defaults to current working directory.\n\nReturns:\n    A sorted list of dotted module paths."
+          },
+          "MkDocsRenderer": {
+            "name": "MkDocsRenderer",
+            "kind": "class",
+            "path": "docforge.cli.mkdocs_utils.MkDocsRenderer",
+            "signature": "<bound method Alias.signature of Alias('MkDocsRenderer', 'docforge.renderers.MkDocsRenderer')>",
+            "docstring": "Renderer that generates Markdown source files formatted for the MkDocs\n'mkdocstrings' plugin.",
+            "members": {
+              "name": {
+                "name": "name",
+                "kind": "attribute",
+                "path": "docforge.cli.mkdocs_utils.MkDocsRenderer.name",
+                "signature": "<bound method Alias.signature of Alias('name', 'docforge.renderers.mkdocs_renderer.MkDocsRenderer.name')>",
+                "docstring": null
+              },
+              "generate_sources": {
+                "name": "generate_sources",
+                "kind": "function",
+                "path": "docforge.cli.mkdocs_utils.MkDocsRenderer.generate_sources",
+                "signature": "<bound method Alias.signature of Alias('generate_sources', 'docforge.renderers.mkdocs_renderer.MkDocsRenderer.generate_sources')>",
+                "docstring": "Produce a set of Markdown files in the output directory based on the\nprovided Project models.\n\nArgs:\n    project: The project models to render.\n    out_dir: Target directory for documentation files.\n    module_is_source: Module is the source folder and to be treated as the root folder."
+              }
+            }
+          },
+          "load_nav_spec": {
+            "name": "load_nav_spec",
+            "kind": "function",
+            "path": "docforge.cli.mkdocs_utils.load_nav_spec",
+            "signature": "<bound method Alias.signature of Alias('load_nav_spec', 'docforge.nav.load_nav_spec')>",
+            "docstring": "Utility function to load a NavSpec from a file.\n\nArgs:\n    path: Path to the navigation specification file.\n\nReturns:\n    A loaded NavSpec instance."
+          },
+          "resolve_nav": {
+            "name": "resolve_nav",
+            "kind": "function",
+            "path": "docforge.cli.mkdocs_utils.resolve_nav",
+            "signature": "<bound method Alias.signature of Alias('resolve_nav', 'docforge.nav.resolve_nav')>",
+            "docstring": "Create a ResolvedNav by processing a NavSpec against the filesystem.\nThis expands globs and validates the existence of referenced files.\n\nArgs:\n    spec: The navigation specification to resolve.\n    docs_root: The root directory for documentation files.\n\nReturns:\n    A ResolvedNav instance.\n\nRaises:\n    FileNotFoundError: If a pattern doesn't match any files or the docs_root doesn't exist."
+          },
+          "MkDocsNavEmitter": {
+            "name": "MkDocsNavEmitter",
+            "kind": "class",
+            "path": "docforge.cli.mkdocs_utils.MkDocsNavEmitter",
+            "signature": "<bound method Alias.signature of Alias('MkDocsNavEmitter', 'docforge.nav.MkDocsNavEmitter')>",
+            "docstring": "Emitter responsible for transforming a ResolvedNav into an MkDocs-compatible\nnavigation structure.",
+            "members": {
+              "emit": {
+                "name": "emit",
+                "kind": "function",
+                "path": "docforge.cli.mkdocs_utils.MkDocsNavEmitter.emit",
+                "signature": "<bound method Alias.signature of Alias('emit', 'docforge.nav.mkdocs.MkDocsNavEmitter.emit')>",
+                "docstring": "Generate a list of navigation entries for mkdocs.yml.\n\nArgs:\n    nav: The resolved navigation data.\n\nReturns:\n    A list of dictionary mappings representing the MkDocs navigation."
+              }
+            }
+          },
+          "generate_sources": {
+            "name": "generate_sources",
+            "kind": "function",
+            "path": "docforge.cli.mkdocs_utils.generate_sources",
+            "signature": "<bound method Function.signature of Function('generate_sources', 9, 33)>",
+            "docstring": "Generate Markdown source files for the specified module.\n\nArgs:\n    module: The dotted path of the primary module to document.\n    project_name: Optional override for the project name.\n    docs_dir: Directory where the generated Markdown files will be written.\n    module_is_source: Module is the source folder and to be treated as the root folder."
+          },
+          "generate_config": {
+            "name": "generate_config",
+            "kind": "function",
+            "path": "docforge.cli.mkdocs_utils.generate_config",
+            "signature": "<bound method Function.signature of Function('generate_config', 35, 69)>",
+            "docstring": "Generate an mkdocs.yml configuration file.\n\nArgs:\n    docs_dir: Path to the directory containing documentation Markdown files.\n    nav_file: Path to the docforge.nav.yml specification.\n    template: Optional path to an mkdocs.yml template (overrides built-in).\n    out: Path where the final mkdocs.yml will be written.\n    site_name: The display name for the documentation site."
+          },
+          "build": {
+            "name": "build",
+            "kind": "function",
+            "path": "docforge.cli.mkdocs_utils.build",
+            "signature": "<bound method Function.signature of Function('build', 71, 84)>",
+            "docstring": "Build the documentation site using MkDocs.\n\nArgs:\n    mkdocs_yml: Path to the mkdocs.yml configuration file."
+          },
+          "serve": {
+            "name": "serve",
+            "kind": "function",
+            "path": "docforge.cli.mkdocs_utils.serve",
+            "signature": "<bound method Function.signature of Function('serve', 86, 97)>",
+            "docstring": "Serve the documentation site with live-reload using MkDocs.\n\nArgs:\n    mkdocs_yml: Path to the mkdocs.yml configuration file."
           }
         }
       }

mcp_docs/modules/docforge.cli.main.json

@@ -2,20 +2,20 @@
   "module": "docforge.cli.main",
   "content": {
     "path": "docforge.cli.main",
-    "docstring": "Main entry point for the doc-forge CLI.",
+    "docstring": "Main entry point for the doc-forge CLI. This module delegates all command\nexecution to docforge.cli.commands.",
     "objects": {
       "cli": {
         "name": "cli",
-        "kind": "function",
+        "kind": "attribute",
         "path": "docforge.cli.main.cli",
         "signature": "<bound method Alias.signature of Alias('cli', 'docforge.cli.commands.cli')>",
-        "docstring": "doc-forge CLI: A tool for introspecting Python projects and generating\ndocumentation."
+        "docstring": null
       },
       "main": {
         "name": "main",
         "kind": "function",
         "path": "docforge.cli.main.main",
-        "signature": "<bound method Function.signature of Function('main', 6, 10)>",
+        "signature": "<bound method Function.signature of Function('main', 7, 11)>",
         "docstring": "CLI Entry point. Boots the click application."
       }
     }

mcp_docs/modules/docforge.cli.mcp.json

@@ -1,129 +0,0 @@
-{
-  "module": "docforge.cli.mcp",
-  "content": {
-    "path": "docforge.cli.mcp",
-    "docstring": null,
-    "objects": {
-      "logic": {
-        "name": "logic",
-        "kind": "module",
-        "path": "docforge.cli.mcp.logic",
-        "signature": null,
-        "docstring": null,
-        "members": {
-          "Path": {
-            "name": "Path",
-            "kind": "alias",
-            "path": "docforge.cli.mcp.logic.Path",
-            "signature": "<bound method Alias.signature of Alias('Path', 'pathlib.Path')>",
-            "docstring": null
-          },
-          "click": {
-            "name": "click",
-            "kind": "alias",
-            "path": "docforge.cli.mcp.logic.click",
-            "signature": "<bound method Alias.signature of Alias('click', 'click')>",
-            "docstring": null
-          },
-          "GriffeLoader": {
-            "name": "GriffeLoader",
-            "kind": "class",
-            "path": "docforge.cli.mcp.logic.GriffeLoader",
-            "signature": "<bound method Alias.signature of Alias('GriffeLoader', 'docforge.loaders.GriffeLoader')>",
-            "docstring": "Loads Python modules and extracts documentation using the Griffe introspection engine.",
-            "members": {
-              "load_project": {
-                "name": "load_project",
-                "kind": "function",
-                "path": "docforge.cli.mcp.logic.GriffeLoader.load_project",
-                "signature": "<bound method Alias.signature of Alias('load_project', 'docforge.loaders.griffe_loader.GriffeLoader.load_project')>",
-                "docstring": "Load multiple modules and combine them into a single Project models.\n\nArgs:\n    module_paths: A list of dotted paths to the modules to load.\n    project_name: Optional name for the project. Defaults to the first module name.\n    skip_import_errors: If True, modules that fail to import will be skipped.\n\nReturns:\n    A Project instance containing the loaded modules."
-              },
-              "load_module": {
-                "name": "load_module",
-                "kind": "function",
-                "path": "docforge.cli.mcp.logic.GriffeLoader.load_module",
-                "signature": "<bound method Alias.signature of Alias('load_module', 'docforge.loaders.griffe_loader.GriffeLoader.load_module')>",
-                "docstring": "Load a single module and convert its introspection data into the docforge models.\n\nArgs:\n    path: The dotted path of the module to load.\n\nReturns:\n    A Module instance."
-              }
-            }
-          },
-          "discover_module_paths": {
-            "name": "discover_module_paths",
-            "kind": "function",
-            "path": "docforge.cli.mcp.logic.discover_module_paths",
-            "signature": "<bound method Alias.signature of Alias('discover_module_paths', 'docforge.loaders.discover_module_paths')>",
-            "docstring": "Discover all Python modules under a package via filesystem traversal.\n\nRules:\n- Directory with __init__.py is treated as a package.\n- Any .py file is treated as a module.\n- All paths are converted to dotted module paths.\n\nArgs:\n    module_name: The name of the package to discover.\n    project_root: The root directory of the project. Defaults to current working directory.\n\nReturns:\n    A sorted list of dotted module paths."
-          },
-          "MCPRenderer": {
-            "name": "MCPRenderer",
-            "kind": "class",
-            "path": "docforge.cli.mcp.logic.MCPRenderer",
-            "signature": "<bound method Alias.signature of Alias('MCPRenderer', 'docforge.renderers.MCPRenderer')>",
-            "docstring": "Renderer that emits MCP-native JSON resources from docforge models.",
-            "members": {
-              "name": {
-                "name": "name",
-                "kind": "attribute",
-                "path": "docforge.cli.mcp.logic.MCPRenderer.name",
-                "signature": "<bound method Alias.signature of Alias('name', 'docforge.renderers.mcp_renderer.MCPRenderer.name')>",
-                "docstring": null
-              },
-              "generate_sources": {
-                "name": "generate_sources",
-                "kind": "function",
-                "path": "docforge.cli.mcp.logic.MCPRenderer.generate_sources",
-                "signature": "<bound method Alias.signature of Alias('generate_sources', 'docforge.renderers.mcp_renderer.MCPRenderer.generate_sources')>",
-                "docstring": "Generate MCP-compatible JSON resources and navigation for the project."
-              }
-            }
-          },
-          "MCPServer": {
-            "name": "MCPServer",
-            "kind": "class",
-            "path": "docforge.cli.mcp.logic.MCPServer",
-            "signature": "<bound method Alias.signature of Alias('MCPServer', 'docforge.servers.MCPServer')>",
-            "docstring": "MCP server for serving a pre-built MCP documentation bundle.",
-            "members": {
-              "mcp_root": {
-                "name": "mcp_root",
-                "kind": "attribute",
-                "path": "docforge.cli.mcp.logic.MCPServer.mcp_root",
-                "signature": "<bound method Alias.signature of Alias('mcp_root', 'docforge.servers.mcp_server.MCPServer.mcp_root')>",
-                "docstring": null
-              },
-              "app": {
-                "name": "app",
-                "kind": "attribute",
-                "path": "docforge.cli.mcp.logic.MCPServer.app",
-                "signature": "<bound method Alias.signature of Alias('app', 'docforge.servers.mcp_server.MCPServer.app')>",
-                "docstring": null
-              },
-              "run": {
-                "name": "run",
-                "kind": "function",
-                "path": "docforge.cli.mcp.logic.MCPServer.run",
-                "signature": "<bound method Alias.signature of Alias('run', 'docforge.servers.mcp_server.MCPServer.run')>",
-                "docstring": "Start the MCP server.\n\nArgs:\n    transport: MCP transport (default: streamable-http)"
-              }
-            }
-          },
-          "generate_resources": {
-            "name": "generate_resources",
-            "kind": "function",
-            "path": "docforge.cli.mcp.logic.generate_resources",
-            "signature": "<bound method Function.signature of Function('generate_resources', 7, 16)>",
-            "docstring": "Generate MCP-compatible documentation resources."
-          },
-          "serve": {
-            "name": "serve",
-            "kind": "function",
-            "path": "docforge.cli.mcp.logic.serve",
-            "signature": "<bound method Function.signature of Function('serve', 18, 39)>",
-            "docstring": "Serve MCP documentation."
-          }
-        }
-      }
-    }
-  }
-}

mcp_docs/modules/docforge.cli.mcp_utils.json

@@ -1,41 +1,41 @@
 {
-  "module": "docforge.cli.mcp.logic",
+  "module": "docforge.cli.mcp_utils",
   "content": {
-    "path": "docforge.cli.mcp.logic",
+    "path": "docforge.cli.mcp_utils",
     "docstring": null,
     "objects": {
       "Path": {
         "name": "Path",
         "kind": "alias",
-        "path": "docforge.cli.mcp.logic.Path",
+        "path": "docforge.cli.mcp_utils.Path",
         "signature": "<bound method Alias.signature of Alias('Path', 'pathlib.Path')>",
         "docstring": null
       },
       "click": {
         "name": "click",
         "kind": "alias",
-        "path": "docforge.cli.mcp.logic.click",
+        "path": "docforge.cli.mcp_utils.click",
         "signature": "<bound method Alias.signature of Alias('click', 'click')>",
         "docstring": null
       },
       "GriffeLoader": {
         "name": "GriffeLoader",
         "kind": "class",
-        "path": "docforge.cli.mcp.logic.GriffeLoader",
+        "path": "docforge.cli.mcp_utils.GriffeLoader",
         "signature": "<bound method Alias.signature of Alias('GriffeLoader', 'docforge.loaders.GriffeLoader')>",
         "docstring": "Loads Python modules and extracts documentation using the Griffe introspection engine.",
         "members": {
           "load_project": {
             "name": "load_project",
             "kind": "function",
-            "path": "docforge.cli.mcp.logic.GriffeLoader.load_project",
+            "path": "docforge.cli.mcp_utils.GriffeLoader.load_project",
             "signature": "<bound method Alias.signature of Alias('load_project', 'docforge.loaders.griffe_loader.GriffeLoader.load_project')>",
             "docstring": "Load multiple modules and combine them into a single Project models.\n\nArgs:\n    module_paths: A list of dotted paths to the modules to load.\n    project_name: Optional name for the project. Defaults to the first module name.\n    skip_import_errors: If True, modules that fail to import will be skipped.\n\nReturns:\n    A Project instance containing the loaded modules."
           },
           "load_module": {
             "name": "load_module",
             "kind": "function",
-            "path": "docforge.cli.mcp.logic.GriffeLoader.load_module",
+            "path": "docforge.cli.mcp_utils.GriffeLoader.load_module",
             "signature": "<bound method Alias.signature of Alias('load_module', 'docforge.loaders.griffe_loader.GriffeLoader.load_module')>",
             "docstring": "Load a single module and convert its introspection data into the docforge models.\n\nArgs:\n    path: The dotted path of the module to load.\n\nReturns:\n    A Module instance."
           }
@@ -44,58 +44,58 @@
       "discover_module_paths": {
         "name": "discover_module_paths",
         "kind": "function",
-        "path": "docforge.cli.mcp.logic.discover_module_paths",
+        "path": "docforge.cli.mcp_utils.discover_module_paths",
         "signature": "<bound method Alias.signature of Alias('discover_module_paths', 'docforge.loaders.discover_module_paths')>",
         "docstring": "Discover all Python modules under a package via filesystem traversal.\n\nRules:\n- Directory with __init__.py is treated as a package.\n- Any .py file is treated as a module.\n- All paths are converted to dotted module paths.\n\nArgs:\n    module_name: The name of the package to discover.\n    project_root: The root directory of the project. Defaults to current working directory.\n\nReturns:\n    A sorted list of dotted module paths."
       },
       "MCPRenderer": {
         "name": "MCPRenderer",
         "kind": "class",
-        "path": "docforge.cli.mcp.logic.MCPRenderer",
+        "path": "docforge.cli.mcp_utils.MCPRenderer",
         "signature": "<bound method Alias.signature of Alias('MCPRenderer', 'docforge.renderers.MCPRenderer')>",
         "docstring": "Renderer that emits MCP-native JSON resources from docforge models.",
         "members": {
           "name": {
             "name": "name",
             "kind": "attribute",
-            "path": "docforge.cli.mcp.logic.MCPRenderer.name",
+            "path": "docforge.cli.mcp_utils.MCPRenderer.name",
             "signature": "<bound method Alias.signature of Alias('name', 'docforge.renderers.mcp_renderer.MCPRenderer.name')>",
             "docstring": null
           },
           "generate_sources": {
             "name": "generate_sources",
             "kind": "function",
-            "path": "docforge.cli.mcp.logic.MCPRenderer.generate_sources",
+            "path": "docforge.cli.mcp_utils.MCPRenderer.generate_sources",
             "signature": "<bound method Alias.signature of Alias('generate_sources', 'docforge.renderers.mcp_renderer.MCPRenderer.generate_sources')>",
-            "docstring": "Generate MCP-compatible JSON resources and navigation for the project."
+            "docstring": "Generate MCP-compatible JSON resources and navigation for the project.\n\nArgs:\n    project: The project model to render.\n    out_dir: Target directory for the generated JSON files."
           }
         }
       },
       "MCPServer": {
         "name": "MCPServer",
         "kind": "class",
-        "path": "docforge.cli.mcp.logic.MCPServer",
+        "path": "docforge.cli.mcp_utils.MCPServer",
         "signature": "<bound method Alias.signature of Alias('MCPServer', 'docforge.servers.MCPServer')>",
         "docstring": "MCP server for serving a pre-built MCP documentation bundle.",
         "members": {
           "mcp_root": {
             "name": "mcp_root",
             "kind": "attribute",
-            "path": "docforge.cli.mcp.logic.MCPServer.mcp_root",
+            "path": "docforge.cli.mcp_utils.MCPServer.mcp_root",
             "signature": "<bound method Alias.signature of Alias('mcp_root', 'docforge.servers.mcp_server.MCPServer.mcp_root')>",
             "docstring": null
           },
           "app": {
             "name": "app",
             "kind": "attribute",
-            "path": "docforge.cli.mcp.logic.MCPServer.app",
+            "path": "docforge.cli.mcp_utils.MCPServer.app",
             "signature": "<bound method Alias.signature of Alias('app', 'docforge.servers.mcp_server.MCPServer.app')>",
             "docstring": null
           },
           "run": {
             "name": "run",
             "kind": "function",
-            "path": "docforge.cli.mcp.logic.MCPServer.run",
+            "path": "docforge.cli.mcp_utils.MCPServer.run",
             "signature": "<bound method Alias.signature of Alias('run', 'docforge.servers.mcp_server.MCPServer.run')>",
             "docstring": "Start the MCP server.\n\nArgs:\n    transport: MCP transport (default: streamable-http)"
           }
@@ -104,16 +104,16 @@
       "generate_resources": {
         "name": "generate_resources",
         "kind": "function",
-        "path": "docforge.cli.mcp.logic.generate_resources",
-        "signature": "<bound method Function.signature of Function('generate_resources', 7, 16)>",
-        "docstring": "Generate MCP-compatible documentation resources."
+        "path": "docforge.cli.mcp_utils.generate_resources",
+        "signature": "<bound method Function.signature of Function('generate_resources', 7, 21)>",
+        "docstring": "Generate MCP-compatible documentation resources.\n\nArgs:\n    module: The dotted path of the primary module to document.\n    project_name: Optional override for the project name.\n    out_dir: Directory where the MCP JSON resources and nav will be written."
       },
       "serve": {
         "name": "serve",
         "kind": "function",
-        "path": "docforge.cli.mcp.logic.serve",
-        "signature": "<bound method Function.signature of Function('serve', 18, 39)>",
-        "docstring": "Serve MCP documentation."
+        "path": "docforge.cli.mcp_utils.serve",
+        "signature": "<bound method Function.signature of Function('serve', 23, 48)>",
+        "docstring": "Serve MCP documentation from a pre-built bundle.\n\nArgs:\n    module: The dotted path of the primary module to serve.\n    mcp_root: Path to the directory containing index.json, nav.json, and modules/."
       }
     }
   }

mcp_docs/modules/docforge.cli.mkdocs.json

@@ -1,157 +0,0 @@
-{
-  "module": "docforge.cli.mkdocs",
-  "content": {
-    "path": "docforge.cli.mkdocs",
-    "docstring": null,
-    "objects": {
-      "logic": {
-        "name": "logic",
-        "kind": "module",
-        "path": "docforge.cli.mkdocs.logic",
-        "signature": null,
-        "docstring": null,
-        "members": {
-          "Path": {
-            "name": "Path",
-            "kind": "alias",
-            "path": "docforge.cli.mkdocs.logic.Path",
-            "signature": "<bound method Alias.signature of Alias('Path', 'pathlib.Path')>",
-            "docstring": null
-          },
-          "resources": {
-            "name": "resources",
-            "kind": "alias",
-            "path": "docforge.cli.mkdocs.logic.resources",
-            "signature": "<bound method Alias.signature of Alias('resources', 'importlib.resources')>",
-            "docstring": null
-          },
-          "click": {
-            "name": "click",
-            "kind": "alias",
-            "path": "docforge.cli.mkdocs.logic.click",
-            "signature": "<bound method Alias.signature of Alias('click', 'click')>",
-            "docstring": null
-          },
-          "yaml": {
-            "name": "yaml",
-            "kind": "alias",
-            "path": "docforge.cli.mkdocs.logic.yaml",
-            "signature": "<bound method Alias.signature of Alias('yaml', 'yaml')>",
-            "docstring": null
-          },
-          "GriffeLoader": {
-            "name": "GriffeLoader",
-            "kind": "class",
-            "path": "docforge.cli.mkdocs.logic.GriffeLoader",
-            "signature": "<bound method Alias.signature of Alias('GriffeLoader', 'docforge.loaders.GriffeLoader')>",
-            "docstring": "Loads Python modules and extracts documentation using the Griffe introspection engine.",
-            "members": {
-              "load_project": {
-                "name": "load_project",
-                "kind": "function",
-                "path": "docforge.cli.mkdocs.logic.GriffeLoader.load_project",
-                "signature": "<bound method Alias.signature of Alias('load_project', 'docforge.loaders.griffe_loader.GriffeLoader.load_project')>",
-                "docstring": "Load multiple modules and combine them into a single Project models.\n\nArgs:\n    module_paths: A list of dotted paths to the modules to load.\n    project_name: Optional name for the project. Defaults to the first module name.\n    skip_import_errors: If True, modules that fail to import will be skipped.\n\nReturns:\n    A Project instance containing the loaded modules."
-              },
-              "load_module": {
-                "name": "load_module",
-                "kind": "function",
-                "path": "docforge.cli.mkdocs.logic.GriffeLoader.load_module",
-                "signature": "<bound method Alias.signature of Alias('load_module', 'docforge.loaders.griffe_loader.GriffeLoader.load_module')>",
-                "docstring": "Load a single module and convert its introspection data into the docforge models.\n\nArgs:\n    path: The dotted path of the module to load.\n\nReturns:\n    A Module instance."
-              }
-            }
-          },
-          "discover_module_paths": {
-            "name": "discover_module_paths",
-            "kind": "function",
-            "path": "docforge.cli.mkdocs.logic.discover_module_paths",
-            "signature": "<bound method Alias.signature of Alias('discover_module_paths', 'docforge.loaders.discover_module_paths')>",
-            "docstring": "Discover all Python modules under a package via filesystem traversal.\n\nRules:\n- Directory with __init__.py is treated as a package.\n- Any .py file is treated as a module.\n- All paths are converted to dotted module paths.\n\nArgs:\n    module_name: The name of the package to discover.\n    project_root: The root directory of the project. Defaults to current working directory.\n\nReturns:\n    A sorted list of dotted module paths."
-          },
-          "MkDocsRenderer": {
-            "name": "MkDocsRenderer",
-            "kind": "class",
-            "path": "docforge.cli.mkdocs.logic.MkDocsRenderer",
-            "signature": "<bound method Alias.signature of Alias('MkDocsRenderer', 'docforge.renderers.MkDocsRenderer')>",
-            "docstring": "Renderer that generates Markdown source files formatted for the MkDocs\n'mkdocstrings' plugin.",
-            "members": {
-              "name": {
-                "name": "name",
-                "kind": "attribute",
-                "path": "docforge.cli.mkdocs.logic.MkDocsRenderer.name",
-                "signature": "<bound method Alias.signature of Alias('name', 'docforge.renderers.mkdocs_renderer.MkDocsRenderer.name')>",
-                "docstring": null
-              },
-              "generate_sources": {
-                "name": "generate_sources",
-                "kind": "function",
-                "path": "docforge.cli.mkdocs.logic.MkDocsRenderer.generate_sources",
-                "signature": "<bound method Alias.signature of Alias('generate_sources', 'docforge.renderers.mkdocs_renderer.MkDocsRenderer.generate_sources')>",
-                "docstring": "Produce a set of Markdown files in the output directory based on the\nprovided Project models.\n\nArgs:\n    project: The project models to render.\n    out_dir: Target directory for documentation files."
-              }
-            }
-          },
-          "load_nav_spec": {
-            "name": "load_nav_spec",
-            "kind": "function",
-            "path": "docforge.cli.mkdocs.logic.load_nav_spec",
-            "signature": "<bound method Alias.signature of Alias('load_nav_spec', 'docforge.nav.load_nav_spec')>",
-            "docstring": "Utility function to load a NavSpec from a file.\n\nArgs:\n    path: Path to the navigation specification file.\n\nReturns:\n    A loaded NavSpec instance."
-          },
-          "resolve_nav": {
-            "name": "resolve_nav",
-            "kind": "function",
-            "path": "docforge.cli.mkdocs.logic.resolve_nav",
-            "signature": "<bound method Alias.signature of Alias('resolve_nav', 'docforge.nav.resolve_nav')>",
-            "docstring": "Create a ResolvedNav by processing a NavSpec against the filesystem.\nThis expands globs and validates the existence of referenced files.\n\nArgs:\n    spec: The navigation specification to resolve.\n    docs_root: The root directory for documentation files.\n\nReturns:\n    A ResolvedNav instance.\n\nRaises:\n    FileNotFoundError: If a pattern doesn't match any files or the docs_root doesn't exist."
-          },
-          "MkDocsNavEmitter": {
-            "name": "MkDocsNavEmitter",
-            "kind": "class",
-            "path": "docforge.cli.mkdocs.logic.MkDocsNavEmitter",
-            "signature": "<bound method Alias.signature of Alias('MkDocsNavEmitter', 'docforge.nav.MkDocsNavEmitter')>",
-            "docstring": "Emitter responsible for transforming a ResolvedNav into an MkDocs-compatible\nnavigation structure.",
-            "members": {
-              "emit": {
-                "name": "emit",
-                "kind": "function",
-                "path": "docforge.cli.mkdocs.logic.MkDocsNavEmitter.emit",
-                "signature": "<bound method Alias.signature of Alias('emit', 'docforge.nav.mkdocs.MkDocsNavEmitter.emit')>",
-                "docstring": "Generate a list of navigation entries for mkdocs.yml.\n\nArgs:\n    nav: The resolved navigation data.\n\nReturns:\n    A list of dictionary mappings representing the MkDocs navigation."
-              }
-            }
-          },
-          "generate_sources": {
-            "name": "generate_sources",
-            "kind": "function",
-            "path": "docforge.cli.mkdocs.logic.generate_sources",
-            "signature": "<bound method Function.signature of Function('generate_sources', 9, 18)>",
-            "docstring": "Generate Markdown source files for the specified module."
-          },
-          "generate_config": {
-            "name": "generate_config",
-            "kind": "function",
-            "path": "docforge.cli.mkdocs.logic.generate_config",
-            "signature": "<bound method Function.signature of Function('generate_config', 20, 47)>",
-            "docstring": "Generate an mkdocs.yml configuration file."
-          },
-          "build": {
-            "name": "build",
-            "kind": "function",
-            "path": "docforge.cli.mkdocs.logic.build",
-            "signature": "<bound method Function.signature of Function('build', 49, 59)>",
-            "docstring": "Build the documentation site using MkDocs."
-          },
-          "serve": {
-            "name": "serve",
-            "kind": "function",
-            "path": "docforge.cli.mkdocs.logic.serve",
-            "signature": "<bound method Function.signature of Function('serve', 61, 69)>",
-            "docstring": "Serve the documentation site with live-reload using MkDocs."
-          }
-        }
-      }
-    }
-  }
-}

mcp_docs/modules/docforge.cli.mkdocs_utils.json

@@ -1,55 +1,55 @@
 {
-  "module": "docforge.cli.mkdocs.logic",
+  "module": "docforge.cli.mkdocs_utils",
   "content": {
-    "path": "docforge.cli.mkdocs.logic",
+    "path": "docforge.cli.mkdocs_utils",
     "docstring": null,
     "objects": {
       "Path": {
         "name": "Path",
         "kind": "alias",
-        "path": "docforge.cli.mkdocs.logic.Path",
+        "path": "docforge.cli.mkdocs_utils.Path",
         "signature": "<bound method Alias.signature of Alias('Path', 'pathlib.Path')>",
         "docstring": null
       },
       "resources": {
         "name": "resources",
         "kind": "alias",
-        "path": "docforge.cli.mkdocs.logic.resources",
+        "path": "docforge.cli.mkdocs_utils.resources",
         "signature": "<bound method Alias.signature of Alias('resources', 'importlib.resources')>",
         "docstring": null
       },
       "click": {
         "name": "click",
         "kind": "alias",
-        "path": "docforge.cli.mkdocs.logic.click",
+        "path": "docforge.cli.mkdocs_utils.click",
         "signature": "<bound method Alias.signature of Alias('click', 'click')>",
         "docstring": null
       },
       "yaml": {
         "name": "yaml",
         "kind": "alias",
-        "path": "docforge.cli.mkdocs.logic.yaml",
+        "path": "docforge.cli.mkdocs_utils.yaml",
         "signature": "<bound method Alias.signature of Alias('yaml', 'yaml')>",
         "docstring": null
       },
       "GriffeLoader": {
         "name": "GriffeLoader",
         "kind": "class",
-        "path": "docforge.cli.mkdocs.logic.GriffeLoader",
+        "path": "docforge.cli.mkdocs_utils.GriffeLoader",
         "signature": "<bound method Alias.signature of Alias('GriffeLoader', 'docforge.loaders.GriffeLoader')>",
         "docstring": "Loads Python modules and extracts documentation using the Griffe introspection engine.",
         "members": {
           "load_project": {
             "name": "load_project",
             "kind": "function",
-            "path": "docforge.cli.mkdocs.logic.GriffeLoader.load_project",
+            "path": "docforge.cli.mkdocs_utils.GriffeLoader.load_project",
             "signature": "<bound method Alias.signature of Alias('load_project', 'docforge.loaders.griffe_loader.GriffeLoader.load_project')>",
             "docstring": "Load multiple modules and combine them into a single Project models.\n\nArgs:\n    module_paths: A list of dotted paths to the modules to load.\n    project_name: Optional name for the project. Defaults to the first module name.\n    skip_import_errors: If True, modules that fail to import will be skipped.\n\nReturns:\n    A Project instance containing the loaded modules."
           },
           "load_module": {
             "name": "load_module",
             "kind": "function",
-            "path": "docforge.cli.mkdocs.logic.GriffeLoader.load_module",
+            "path": "docforge.cli.mkdocs_utils.GriffeLoader.load_module",
             "signature": "<bound method Alias.signature of Alias('load_module', 'docforge.loaders.griffe_loader.GriffeLoader.load_module')>",
             "docstring": "Load a single module and convert its introspection data into the docforge models.\n\nArgs:\n    path: The dotted path of the module to load.\n\nReturns:\n    A Module instance."
           }
@@ -58,58 +58,58 @@
       "discover_module_paths": {
         "name": "discover_module_paths",
         "kind": "function",
-        "path": "docforge.cli.mkdocs.logic.discover_module_paths",
+        "path": "docforge.cli.mkdocs_utils.discover_module_paths",
         "signature": "<bound method Alias.signature of Alias('discover_module_paths', 'docforge.loaders.discover_module_paths')>",
         "docstring": "Discover all Python modules under a package via filesystem traversal.\n\nRules:\n- Directory with __init__.py is treated as a package.\n- Any .py file is treated as a module.\n- All paths are converted to dotted module paths.\n\nArgs:\n    module_name: The name of the package to discover.\n    project_root: The root directory of the project. Defaults to current working directory.\n\nReturns:\n    A sorted list of dotted module paths."
       },
       "MkDocsRenderer": {
         "name": "MkDocsRenderer",
         "kind": "class",
-        "path": "docforge.cli.mkdocs.logic.MkDocsRenderer",
+        "path": "docforge.cli.mkdocs_utils.MkDocsRenderer",
         "signature": "<bound method Alias.signature of Alias('MkDocsRenderer', 'docforge.renderers.MkDocsRenderer')>",
         "docstring": "Renderer that generates Markdown source files formatted for the MkDocs\n'mkdocstrings' plugin.",
         "members": {
           "name": {
             "name": "name",
             "kind": "attribute",
-            "path": "docforge.cli.mkdocs.logic.MkDocsRenderer.name",
+            "path": "docforge.cli.mkdocs_utils.MkDocsRenderer.name",
             "signature": "<bound method Alias.signature of Alias('name', 'docforge.renderers.mkdocs_renderer.MkDocsRenderer.name')>",
             "docstring": null
           },
           "generate_sources": {
             "name": "generate_sources",
             "kind": "function",
-            "path": "docforge.cli.mkdocs.logic.MkDocsRenderer.generate_sources",
+            "path": "docforge.cli.mkdocs_utils.MkDocsRenderer.generate_sources",
             "signature": "<bound method Alias.signature of Alias('generate_sources', 'docforge.renderers.mkdocs_renderer.MkDocsRenderer.generate_sources')>",
-            "docstring": "Produce a set of Markdown files in the output directory based on the\nprovided Project models.\n\nArgs:\n    project: The project models to render.\n    out_dir: Target directory for documentation files."
+            "docstring": "Produce a set of Markdown files in the output directory based on the\nprovided Project models.\n\nArgs:\n    project: The project models to render.\n    out_dir: Target directory for documentation files.\n    module_is_source: Module is the source folder and to be treated as the root folder."
           }
         }
       },
       "load_nav_spec": {
         "name": "load_nav_spec",
         "kind": "function",
-        "path": "docforge.cli.mkdocs.logic.load_nav_spec",
+        "path": "docforge.cli.mkdocs_utils.load_nav_spec",
         "signature": "<bound method Alias.signature of Alias('load_nav_spec', 'docforge.nav.load_nav_spec')>",
         "docstring": "Utility function to load a NavSpec from a file.\n\nArgs:\n    path: Path to the navigation specification file.\n\nReturns:\n    A loaded NavSpec instance."
       },
       "resolve_nav": {
         "name": "resolve_nav",
         "kind": "function",
-        "path": "docforge.cli.mkdocs.logic.resolve_nav",
+        "path": "docforge.cli.mkdocs_utils.resolve_nav",
         "signature": "<bound method Alias.signature of Alias('resolve_nav', 'docforge.nav.resolve_nav')>",
         "docstring": "Create a ResolvedNav by processing a NavSpec against the filesystem.\nThis expands globs and validates the existence of referenced files.\n\nArgs:\n    spec: The navigation specification to resolve.\n    docs_root: The root directory for documentation files.\n\nReturns:\n    A ResolvedNav instance.\n\nRaises:\n    FileNotFoundError: If a pattern doesn't match any files or the docs_root doesn't exist."
       },
       "MkDocsNavEmitter": {
         "name": "MkDocsNavEmitter",
         "kind": "class",
-        "path": "docforge.cli.mkdocs.logic.MkDocsNavEmitter",
+        "path": "docforge.cli.mkdocs_utils.MkDocsNavEmitter",
         "signature": "<bound method Alias.signature of Alias('MkDocsNavEmitter', 'docforge.nav.MkDocsNavEmitter')>",
         "docstring": "Emitter responsible for transforming a ResolvedNav into an MkDocs-compatible\nnavigation structure.",
         "members": {
           "emit": {
             "name": "emit",
             "kind": "function",
-            "path": "docforge.cli.mkdocs.logic.MkDocsNavEmitter.emit",
+            "path": "docforge.cli.mkdocs_utils.MkDocsNavEmitter.emit",
             "signature": "<bound method Alias.signature of Alias('emit', 'docforge.nav.mkdocs.MkDocsNavEmitter.emit')>",
             "docstring": "Generate a list of navigation entries for mkdocs.yml.\n\nArgs:\n    nav: The resolved navigation data.\n\nReturns:\n    A list of dictionary mappings representing the MkDocs navigation."
           }
@@ -118,30 +118,30 @@
       "generate_sources": {
         "name": "generate_sources",
         "kind": "function",
-        "path": "docforge.cli.mkdocs.logic.generate_sources",
-        "signature": "<bound method Function.signature of Function('generate_sources', 9, 18)>",
-        "docstring": "Generate Markdown source files for the specified module."
+        "path": "docforge.cli.mkdocs_utils.generate_sources",
+        "signature": "<bound method Function.signature of Function('generate_sources', 9, 33)>",
+        "docstring": "Generate Markdown source files for the specified module.\n\nArgs:\n    module: The dotted path of the primary module to document.\n    project_name: Optional override for the project name.\n    docs_dir: Directory where the generated Markdown files will be written.\n    module_is_source: Module is the source folder and to be treated as the root folder."
       },
       "generate_config": {
         "name": "generate_config",
         "kind": "function",
-        "path": "docforge.cli.mkdocs.logic.generate_config",
-        "signature": "<bound method Function.signature of Function('generate_config', 20, 47)>",
-        "docstring": "Generate an mkdocs.yml configuration file."
+        "path": "docforge.cli.mkdocs_utils.generate_config",
+        "signature": "<bound method Function.signature of Function('generate_config', 35, 69)>",
+        "docstring": "Generate an mkdocs.yml configuration file.\n\nArgs:\n    docs_dir: Path to the directory containing documentation Markdown files.\n    nav_file: Path to the docforge.nav.yml specification.\n    template: Optional path to an mkdocs.yml template (overrides built-in).\n    out: Path where the final mkdocs.yml will be written.\n    site_name: The display name for the documentation site."
       },
       "build": {
         "name": "build",
         "kind": "function",
-        "path": "docforge.cli.mkdocs.logic.build",
-        "signature": "<bound method Function.signature of Function('build', 49, 59)>",
-        "docstring": "Build the documentation site using MkDocs."
+        "path": "docforge.cli.mkdocs_utils.build",
+        "signature": "<bound method Function.signature of Function('build', 71, 84)>",
+        "docstring": "Build the documentation site using MkDocs.\n\nArgs:\n    mkdocs_yml: Path to the mkdocs.yml configuration file."
       },
       "serve": {
         "name": "serve",
         "kind": "function",
-        "path": "docforge.cli.mkdocs.logic.serve",
-        "signature": "<bound method Function.signature of Function('serve', 61, 69)>",
-        "docstring": "Serve the documentation site with live-reload using MkDocs."
+        "path": "docforge.cli.mkdocs_utils.serve",
+        "signature": "<bound method Function.signature of Function('serve', 86, 97)>",
+        "docstring": "Serve the documentation site with live-reload using MkDocs.\n\nArgs:\n    mkdocs_yml: Path to the mkdocs.yml configuration file."
       }
     }
   }

mcp_docs/modules/docforge.renderers.json

@@ -23,7 +23,7 @@
             "kind": "function",
             "path": "docforge.renderers.MkDocsRenderer.generate_sources",
             "signature": "<bound method Alias.signature of Alias('generate_sources', 'docforge.renderers.mkdocs_renderer.MkDocsRenderer.generate_sources')>",
-            "docstring": "Produce a set of Markdown files in the output directory based on the\nprovided Project models.\n\nArgs:\n    project: The project models to render.\n    out_dir: Target directory for documentation files."
+            "docstring": "Produce a set of Markdown files in the output directory based on the\nprovided Project models.\n\nArgs:\n    project: The project models to render.\n    out_dir: Target directory for documentation files.\n    module_is_source: Module is the source folder and to be treated as the root folder."
           }
         }
       },
@@ -46,7 +46,7 @@
             "kind": "function",
             "path": "docforge.renderers.MCPRenderer.generate_sources",
             "signature": "<bound method Alias.signature of Alias('generate_sources', 'docforge.renderers.mcp_renderer.MCPRenderer.generate_sources')>",
-            "docstring": "Generate MCP-compatible JSON resources and navigation for the project."
+            "docstring": "Generate MCP-compatible JSON resources and navigation for the project.\n\nArgs:\n    project: The project model to render.\n    out_dir: Target directory for the generated JSON files."
           }
         }
       },
@@ -383,7 +383,7 @@
             "name": "MCPRenderer",
             "kind": "class",
             "path": "docforge.renderers.mcp_renderer.MCPRenderer",
-            "signature": "<bound method Class.signature of Class('MCPRenderer', 8, 102)>",
+            "signature": "<bound method Class.signature of Class('MCPRenderer', 8, 122)>",
             "docstring": "Renderer that emits MCP-native JSON resources from docforge models.",
             "members": {
               "name": {
@@ -397,8 +397,8 @@
                 "name": "generate_sources",
                 "kind": "function",
                 "path": "docforge.renderers.mcp_renderer.MCPRenderer.generate_sources",
-                "signature": "<bound method Function.signature of Function('generate_sources', 15, 49)>",
-                "docstring": "Generate MCP-compatible JSON resources and navigation for the project."
+                "signature": "<bound method Function.signature of Function('generate_sources', 15, 53)>",
+                "docstring": "Generate MCP-compatible JSON resources and navigation for the project.\n\nArgs:\n    project: The project model to render.\n    out_dir: Target directory for the generated JSON files."
               }
             }
           }
@@ -409,7 +409,7 @@
         "kind": "module",
         "path": "docforge.renderers.mkdocs_renderer",
         "signature": null,
-        "docstring": "This module implements the MkDocsRenderer, which generates Markdown source files\ncompatible with the MkDocs 'material' theme and 'mkdocstrings' extension.",
+        "docstring": "MkDocsRenderer\n\nGenerates Markdown source files compatible with MkDocs Material\nand mkdocstrings, ensuring:\n\n- Root index.md always exists\n- Parent package indexes are created automatically\n- Child modules are linked in parent index files",
         "members": {
           "Path": {
             "name": "Path",
@@ -469,36 +469,6 @@
               }
             }
           },
-          "MkDocsRenderer": {
-            "name": "MkDocsRenderer",
-            "kind": "class",
-            "path": "docforge.renderers.mkdocs_renderer.MkDocsRenderer",
-            "signature": "<bound method Class.signature of Class('MkDocsRenderer', 11, 91)>",
-            "docstring": "Renderer that generates Markdown source files formatted for the MkDocs\n'mkdocstrings' plugin.",
-            "members": {
-              "name": {
-                "name": "name",
-                "kind": "attribute",
-                "path": "docforge.renderers.mkdocs_renderer.MkDocsRenderer.name",
-                "signature": null,
-                "docstring": null
-              },
-              "generate_sources": {
-                "name": "generate_sources",
-                "kind": "function",
-                "path": "docforge.renderers.mkdocs_renderer.MkDocsRenderer.generate_sources",
-                "signature": "<bound method Function.signature of Function('generate_sources', 19, 38)>",
-                "docstring": "Produce a set of Markdown files in the output directory based on the\nprovided Project models.\n\nArgs:\n    project: The project models to render.\n    out_dir: Target directory for documentation files."
-              }
-            }
-          },
-          "Set": {
-            "name": "Set",
-            "kind": "alias",
-            "path": "docforge.renderers.mkdocs_renderer.Set",
-            "signature": "<bound method Alias.signature of Alias('Set', 'typing.Set')>",
-            "docstring": null
-          },
           "Module": {
             "name": "Module",
             "kind": "class",
@@ -549,6 +519,29 @@
                 "docstring": "Get all top-level objects in the module.\n\nReturns:\n    An iterable of DocObject instances."
               }
             }
+          },
+          "MkDocsRenderer": {
+            "name": "MkDocsRenderer",
+            "kind": "class",
+            "path": "docforge.renderers.mkdocs_renderer.MkDocsRenderer",
+            "signature": "<bound method Class.signature of Class('MkDocsRenderer', 16, 168)>",
+            "docstring": "Renderer that generates Markdown source files formatted for the MkDocs\n'mkdocstrings' plugin.",
+            "members": {
+              "name": {
+                "name": "name",
+                "kind": "attribute",
+                "path": "docforge.renderers.mkdocs_renderer.MkDocsRenderer.name",
+                "signature": null,
+                "docstring": null
+              },
+              "generate_sources": {
+                "name": "generate_sources",
+                "kind": "function",
+                "path": "docforge.renderers.mkdocs_renderer.MkDocsRenderer.generate_sources",
+                "signature": "<bound method Function.signature of Function('generate_sources', 27, 60)>",
+                "docstring": "Produce a set of Markdown files in the output directory based on the\nprovided Project models.\n\nArgs:\n    project: The project models to render.\n    out_dir: Target directory for documentation files.\n    module_is_source: Module is the source folder and to be treated as the root folder."
+              }
+            }
           }
         }
       }

mcp_docs/modules/docforge.renderers.mcp_renderer.json

@@ -210,7 +210,7 @@
         "name": "MCPRenderer",
         "kind": "class",
         "path": "docforge.renderers.mcp_renderer.MCPRenderer",
-        "signature": "<bound method Class.signature of Class('MCPRenderer', 8, 102)>",
+        "signature": "<bound method Class.signature of Class('MCPRenderer', 8, 122)>",
         "docstring": "Renderer that emits MCP-native JSON resources from docforge models.",
         "members": {
           "name": {
@@ -224,8 +224,8 @@
             "name": "generate_sources",
             "kind": "function",
             "path": "docforge.renderers.mcp_renderer.MCPRenderer.generate_sources",
-            "signature": "<bound method Function.signature of Function('generate_sources', 15, 49)>",
-            "docstring": "Generate MCP-compatible JSON resources and navigation for the project."
+            "signature": "<bound method Function.signature of Function('generate_sources', 15, 53)>",
+            "docstring": "Generate MCP-compatible JSON resources and navigation for the project.\n\nArgs:\n    project: The project model to render.\n    out_dir: Target directory for the generated JSON files."
           }
         }
       }

mcp_docs/modules/docforge.renderers.mkdocs_renderer.json

@@ -2,7 +2,7 @@
   "module": "docforge.renderers.mkdocs_renderer",
   "content": {
     "path": "docforge.renderers.mkdocs_renderer",
-    "docstring": "This module implements the MkDocsRenderer, which generates Markdown source files\ncompatible with the MkDocs 'material' theme and 'mkdocstrings' extension.",
+    "docstring": "MkDocsRenderer\n\nGenerates Markdown source files compatible with MkDocs Material\nand mkdocstrings, ensuring:\n\n- Root index.md always exists\n- Parent package indexes are created automatically\n- Child modules are linked in parent index files",
     "objects": {
       "Path": {
         "name": "Path",
@@ -62,36 +62,6 @@
           }
         }
       },
-      "MkDocsRenderer": {
-        "name": "MkDocsRenderer",
-        "kind": "class",
-        "path": "docforge.renderers.mkdocs_renderer.MkDocsRenderer",
-        "signature": "<bound method Class.signature of Class('MkDocsRenderer', 11, 91)>",
-        "docstring": "Renderer that generates Markdown source files formatted for the MkDocs\n'mkdocstrings' plugin.",
-        "members": {
-          "name": {
-            "name": "name",
-            "kind": "attribute",
-            "path": "docforge.renderers.mkdocs_renderer.MkDocsRenderer.name",
-            "signature": null,
-            "docstring": null
-          },
-          "generate_sources": {
-            "name": "generate_sources",
-            "kind": "function",
-            "path": "docforge.renderers.mkdocs_renderer.MkDocsRenderer.generate_sources",
-            "signature": "<bound method Function.signature of Function('generate_sources', 19, 38)>",
-            "docstring": "Produce a set of Markdown files in the output directory based on the\nprovided Project models.\n\nArgs:\n    project: The project models to render.\n    out_dir: Target directory for documentation files."
-          }
-        }
-      },
-      "Set": {
-        "name": "Set",
-        "kind": "alias",
-        "path": "docforge.renderers.mkdocs_renderer.Set",
-        "signature": "<bound method Alias.signature of Alias('Set', 'typing.Set')>",
-        "docstring": null
-      },
       "Module": {
         "name": "Module",
         "kind": "class",
@@ -142,6 +112,29 @@
             "docstring": "Get all top-level objects in the module.\n\nReturns:\n    An iterable of DocObject instances."
           }
         }
+      },
+      "MkDocsRenderer": {
+        "name": "MkDocsRenderer",
+        "kind": "class",
+        "path": "docforge.renderers.mkdocs_renderer.MkDocsRenderer",
+        "signature": "<bound method Class.signature of Class('MkDocsRenderer', 16, 168)>",
+        "docstring": "Renderer that generates Markdown source files formatted for the MkDocs\n'mkdocstrings' plugin.",
+        "members": {
+          "name": {
+            "name": "name",
+            "kind": "attribute",
+            "path": "docforge.renderers.mkdocs_renderer.MkDocsRenderer.name",
+            "signature": null,
+            "docstring": null
+          },
+          "generate_sources": {
+            "name": "generate_sources",
+            "kind": "function",
+            "path": "docforge.renderers.mkdocs_renderer.MkDocsRenderer.generate_sources",
+            "signature": "<bound method Function.signature of Function('generate_sources', 27, 60)>",
+            "docstring": "Produce a set of Markdown files in the output directory based on the\nprovided Project models.\n\nArgs:\n    project: The project models to render.\n    out_dir: Target directory for documentation files.\n    module_is_source: Module is the source folder and to be treated as the root folder."
+          }
+        }
       }
     }
   }

mcp_docs/nav.json

@@ -16,20 +16,12 @@
     "resource": "doc://modules/docforge.cli.main"
   },
   {
-    "module": "docforge.cli.mcp",
-    "resource": "doc://modules/docforge.cli.mcp"
+    "module": "docforge.cli.mcp_utils",
+    "resource": "doc://modules/docforge.cli.mcp_utils"
   },
   {
-    "module": "docforge.cli.mcp.logic",
-    "resource": "doc://modules/docforge.cli.mcp.logic"
-  },
-  {
-    "module": "docforge.cli.mkdocs",
-    "resource": "doc://modules/docforge.cli.mkdocs"
-  },
-  {
-    "module": "docforge.cli.mkdocs.logic",
-    "resource": "doc://modules/docforge.cli.mkdocs.logic"
+    "module": "docforge.cli.mkdocs_utils",
+    "resource": "doc://modules/docforge.cli.mkdocs_utils"
   },
   {
     "module": "docforge.loaders",

mkdocs.yml

@@ -1,5 +1,3 @@
-site_name: docforge
-
 theme:
   name: material
   palette:
@@ -33,32 +31,30 @@ plugins:
           annotations_path: brief
           show_root_heading: true
           group_by_category: true
-
+site_name: docforge
 nav:
-- Home: docforge/index.md
+- Home: index.md
 - Loaders:
-  - docforge/loaders/index.md
-  - docforge/loaders/griffe_loader.md
+  - loaders/index.md
+  - loaders/griffe_loader.md
 - Models:
-  - docforge/models/index.md
-  - docforge/models/module.md
-  - docforge/models/object.md
-  - docforge/models/project.md
+  - models/index.md
+  - models/module.md
+  - models/object.md
+  - models/project.md
 - Navigation:
-  - docforge/nav/index.md
-  - docforge/nav/spec.md
-  - docforge/nav/resolver.md
-  - docforge/nav/mkdocs.md
+  - nav/index.md
+  - nav/spec.md
+  - nav/resolver.md
+  - nav/mkdocs.md
 - Renderers:
-  - docforge/renderers/index.md
-  - docforge/renderers/base.md
-  - docforge/renderers/mkdocs_renderer.md
-  - docforge/renderers/mcp_renderer.md
+  - renderers/index.md
+  - renderers/base.md
+  - renderers/mkdocs_renderer.md
+  - renderers/mcp_renderer.md
 - CLI:
-  - docforge/cli/index.md
-  - docforge/cli/main.md
-  - docforge/cli/commands.md
-  - docforge/cli/mcp/index.md
-  - docforge/cli/mcp/logic.md
-  - docforge/cli/mkdocs/index.md
-  - docforge/cli/mkdocs/logic.md
+  - cli/index.md
+  - cli/main.md
+  - cli/commands.md
+  - cli/mcp_utils.md
+  - cli/mkdocs_utils.md

pyproject.toml

@@ -5,7 +5,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "doc-forge"
-version = "0.0.2"
+version = "0.0.5"
 description = "A renderer-agnostic Python documentation compiler"
 readme = "README.md"
 requires-python = ">=3.10"

tests/cli/test_build_mcp.py

@@ -1,6 +1,4 @@
-import json
 from pathlib import Path
-from click.testing import CliRunner
 from docforge.cli.main import cli
 
 def test_mcp_build(cli_runner):

tests/cli/test_build_mkdocs.py

@@ -48,7 +48,52 @@ def test_mkdocs_build_missing_module_fails(cli_runner):
     assert result.exit_code != 0
     assert "--module is required" in result.output
 
-def test_mkdocs_build_missing_site_name_fails(cli_runner):
-    result = cli_runner.invoke(cli, ["build", "--mkdocs", "--module", "testpkg"])
-    assert result.exit_code != 0
-    assert "--site-name is required" in result.output
+def test_mkdocs_build_without_site_name_uses_module_as_default_full_flow(
+    cli_runner,
+    mock_mkdocs_build,
+    mock_mkdocs_load_config,
+):
+    # Full integration test: real generation, real config, mocked mkdocs build
+    with cli_runner.isolated_filesystem():
+        cwd = Path.cwd()
+
+        # Create a minimal Python package
+        pkg = cwd / "testpkg"
+        pkg.mkdir()
+        (pkg / "__init__.py").write_text("")
+        (pkg / "mod.py").write_text("def f(): ...\n")
+
+        # Create nav spec expected by generate_config
+        nav_file = cwd / "docforge.nav.yml"
+        nav_file.write_text(
+            "home: testpkg/index.md\ngroups: {}\n",
+            encoding="utf-8",
+        )
+
+        result = cli_runner.invoke(
+            cli,
+            [
+                "build",
+                "--mkdocs",
+                "--module",
+                "testpkg",
+                "--docs-dir",
+                "docs",
+                "--mkdocs-yml",
+                "mkdocs.yml",
+            ],
+        )
+
+        assert result.exit_code == 0
+        assert mock_mkdocs_build() is True
+
+        # MkDocs config must exist
+        mkdocs_yml = cwd / "mkdocs.yml"
+        assert mkdocs_yml.exists()
+
+        # Site name must default to module name
+        content = mkdocs_yml.read_text()
+        assert "site_name: testpkg" in content
+
+        # Docs must be generated
+        assert (cwd / "docs" / "testpkg" / "mod.md").exists()

tests/cli/test_serve_mcp.py

@@ -10,7 +10,7 @@ def test_mcp_serve(
 
     result = cli_runner.invoke(
         cli,
-        ["serve", "--mcp", "--out-dir", str(fake_mcp_docs)],
+        ["serve", "--mcp", "--module", "fake_module", "--out-dir", str(fake_mcp_docs)],
     )
 
     assert result.exit_code == 0