Flatten MkDocs Structure + --module-is-source Support (#4)

# 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>

mcp_docs/modules/docforge.cli.commands.json

@@ -139,7 +139,7 @@
                 "kind": "function",
                 "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."
               }
             }
           },
@@ -178,7 +178,7 @@
             "kind": "function",
             "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."
+            "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",
@@ -319,7 +319,7 @@
             "kind": "function",
             "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    mcp_root: Path to the directory containing index.json, nav.json, and modules/."
+            "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/."
           }
         }
       },
@@ -334,22 +334,22 @@
         "name": "build",
         "kind": "function",
         "path": "docforge.cli.commands.build",
-        "signature": "<bound method Function.signature of Function('build', 18, 89)>",
-        "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: The dotted path of the module to 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."
+        "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', 92, 120)>",
-        "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    mkdocs_yml: (MkDocs) Path to the mkdocs.yml configuration.\n    out_dir: (MCP) Path to the mcp_docs/ directory."
+        "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', 123, 153)>",
-        "docstring": "Visualize the project structure in the terminal.\n\nArgs:\n    modules: List of module import paths to recursively introspect.\n    project_name: Optional override for the project name shown at the root."
+        "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",