doc changes

- Consolidated CLI commands into [build](cci:1://file:///c:/Users/vishe/WorkSpace/code/aetos/doc-forge/docforge/cli/mkdocs/logic.py:48:0-58:46) and [serve](cci:1://file:///c:/Users/vishe/WorkSpace/code/aetos/doc-forge/docforge/cli/commands.py:70:0-92:32) using `--mkdocs` and `--mcp` flags.
- Separated CLI orchestration logic into [docforge/cli/mkdocs/logic.py](cci:7://file:///c:/Users/vishe/WorkSpace/code/aetos/doc-forge/docforge/cli/mkdocs/logic.py:0:0-0:0) and [docforge/cli/mcp/logic.py](cci:7://file:///c:/Users/vishe/WorkSpace/code/aetos/doc-forge/docforge/cli/mcp/logic.py:0:0-0:0).
- Moved command definitions to [docforge/cli/commands.py](cci:7://file:///c:/Users/vishe/WorkSpace/code/aetos/doc-forge/docforge/cli/commands.py:0:0-0:0), making [main.py](cci:7://file:///c:/Users/vishe/WorkSpace/code/aetos/doc-forge/docforge/cli/main.py:0:0-0:0) a thin entry point.
- Aligned [.pyi](cci:7://file:///c:/Users/vishe/WorkSpace/code/aetos/doc-forge/docforge/cli/main.pyi:0:0-0:0) type stubs with [.py](cci:7://file:///c:/Users/vishe/WorkSpace/code/aetos/doc-forge/tests/conftest.py:0:0-0:0) implementations across the package.
- Added missing docstrings to internal helper functions and core classes.
- Restructured tests into `tests/mkdocs/` and `tests/mcp/`.
- Updated navigation specification to reflect the new project structure.

.run/pytest.run.xml

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

ADS.llm.md

@@ -0,0 +1,327 @@
+# 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.*

README.md

@@ -1,534 +1,244 @@
-# docforge
+# doc-forge
 
-Renderer-agnostic Python documentation compiler that converts Python docstrings
-into structured documentation for both humans (MkDocs) and machines (MCP / AI agents).
+A renderer-agnostic Python documentation compiler that converts Python source code and docstrings into a structured, semantic documentation model and emits multiple downstream representations.
 
-`doc-forge` statically analyzes source code, builds a semantic model of modules,
-classes, functions, and attributes, and renders that model into documentation
-outputs without executing user code.
+## Features
 
----
+- **Single Source of Truth**: Python source code and docstrings are the only authoritative input
+- **Renderer Agnosticism**: MkDocs, Sphinx, MCP, or future renderers don't influence the core model
+- **Deterministic Output**: Given the same codebase, outputs are reproducible
+- **AI-Native Documentation**: Structured, queryable, and machine-consumable
+- **Library-First Design**: All functionality accessible as a Python API
 
 ## Installation
 
-Install using pip:
+```bash
+pip install doc-forge
+```
 
-    pip install doc-forge
+### Optional Dependencies
 
----
+```bash
+# For MkDocs rendering
+pip install doc-forge[mkdocs]
 
-## Quick start
+# For Sphinx rendering  
+pip install doc-forge[sphinx]
 
-Generate a MkDocs site from a Python package:
+# For MCP support
+pip install doc-forge[mcp]
 
-    doc-forge build --mkdocs --module my_package
+# For development
+pip install doc-forge[dev]
+```
 
-Generate MCP JSON documentation:
+## Quick Start
 
-    doc-forge build --mcp --module my_package
+### Command Line Interface
 
-Serve documentation locally:
+```bash
+# Generate MkDocs documentation
+doc-forge generate --renderer mkdocs mypackage
 
-    doc-forge serve --mkdocs --module my_package
+# Build final HTML documentation
+doc-forge build --renderer mkdocs mypackage
 
----
+# Serve documentation locally
+doc-forge serve --renderer mkdocs mypackage
 
-## Core concepts
+# Export to MCP format
+doc-forge export mypackage
 
-**Loader**
+# Start live MCP server
+doc-forge server mypackage
+```
 
-Extracts symbols, signatures, and docstrings using static analysis.
+### Python API
 
-**Semantic model**
+```python
+from docforge.loaders import GriffeLoader
+from docforge.renderers import MkDocsRenderer
+from pathlib import Path
 
-Structured, renderer-agnostic representation of the API.
+# Load your project
+loader = GriffeLoader()
+project = loader.load_project(["mypackage", "mypackage.utils"])
 
-**Renderer**
+# Generate MkDocs sources
+renderer = MkDocsRenderer()
+renderer.generate_sources(project, Path("docs"))
 
-Converts the semantic model into output formats such as MkDocs or MCP JSON.
+# Build final documentation
+from docforge.renderers.base import RendererConfig
 
-**Symbol**
-
-Any documentable object:
-
-    - module
-    - class
-    - function
-    - method
-    - property
-    - attribute
-
----
+config = RendererConfig(Path("docs"), project)
+renderer.build(config)
+```
 
 ## Architecture
 
-`doc-forge` follows a compiler architecture:
+doc-forge follows this high-level architecture:
 
-Front-end:
-
-    Static analysis of modules, classes, functions, type hints, and docstrings.
-
-Middle-end:
-
-    Builds a semantic model describing symbols and relationships.
-
-Back-end:
-
-    Renders documentation using interchangeable renderers.
-
-This architecture ensures deterministic documentation generation.
-
----
-
-## Rendering pipeline
-
-Typical flow:
-
-    Python package
+```
+Python Source Code
         ↓
-    Loader (static analysis)
+Introspection Layer (Griffe)
         ↓
-    Semantic model
+Documentation Model (doc-forge core)
         ↓
-    Renderer
-        ↓
-    MkDocs site or MCP JSON
+Renderer / Exporter Layer
+   ├── MkDocs
+   ├── Sphinx
+   ├── MCP (static JSON)
+   └── MCP Server (live)
+```
+
+## Core Components
+
+### Documentation Model
+
+- **Project**: Root container for all documentation
+- **Module**: Represents Python modules
+- **DocObject**: Base class for classes, functions, variables, etc.
+- **Navigation**: Hierarchical structure for browsing
+
+### Renderers
+
+- **MkDocs Renderer**: Generates Markdown with mkdocstrings directives
+- **Sphinx Renderer**: Generates reStructuredText with autodoc directives
+
+### Exporters
+
+- **MCP Exporter**: Creates static JSON bundles for machine consumption
+- **MCP Server**: Live server for real-time documentation access
+
+## CLI Commands
+
+### `generate`
+Generate renderer-specific source files without building final artifacts.
+
+```bash
+doc-forge generate --renderer mkdocs --out-dir docs mypackage
+```
+
+### `build`
+Build final documentation artifacts (HTML, etc.).
+
+```bash
+doc-forge build --renderer sphinx mypackage
+```
+
+### `serve`
+Start a local development server.
+
+```bash
+doc-forge serve --renderer mkdocs --port 9000 mypackage
+```
+
+### `export`
+Export to MCP format for machine consumption.
+
+```bash
+doc-forge export --out-dir mcp mypackage
+```
+
+### `server`
+Start live MCP server for real-time access.
+
+```bash
+doc-forge server --host 0.0.0.0 --port 8080 mypackage
+```
+
+## Configuration
+
+doc-forge is designed to work with minimal configuration. Most settings are derived automatically from your Python code structure.
+
+### MkDocs Configuration
+
+The MkDocs renderer automatically generates `mkdocs.yml` with sensible defaults:
+
+```yaml
+site_name: Your Project
+plugins:
+  - mkdocstrings
+theme:
+  name: material
+```
+
+### Sphinx Configuration
+
+The Sphinx renderer automatically generates `conf.py` with standard extensions:
+
+```python
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.viewcode', 
+    'sphinx.ext.napoleon',
+]
+```
+
+## MCP Integration
+
+doc-forge provides two ways to integrate with MCP (Model Context Protocol):
+
+### Static Export
+```bash
+doc-forge export mypackage
+```
+Creates a static JSON bundle in `mcp/` directory that can be loaded by MCP clients.
+
+### Live Server
+```bash
+doc-forge server mypackage
+```
+Starts a live MCP server providing real-time access to documentation resources:
+
+- `docs://index` - Project metadata
+- `docs://nav` - Navigation structure
+- `docs://module/{module}` - Individual module data
+
+## Development
+
+### Setup
+
+```bash
+git clone https://github.com/doc-forge/doc-forge
+cd doc-forge
+pip install -e ".[dev]"
+```
+
+### Running Tests
+
+```bash
+pytest
+```
+
+### Code Quality
+
+```bash
+black docforge/
+ruff check docforge/
+mypy docforge/
+```
+
+## License
+
+MIT License - see LICENSE file for details.
+
+## Contributing
+
+Contributions are welcome! Please see CONTRIBUTING.md for guidelines.
+
+## Philosophy
+
+doc-forge is built on these core principles:
+
+1. **Single Source of Truth**: Python source code and docstrings are the only authoritative input
+2. **Renderer Agnosticism**: The core model contains no renderer-specific logic
+3. **Deterministic Output**: Same input always produces same output
+4. **AI-Native Documentation**: Documentation must be structured, queryable, and machine-consumable
+5. **Library-First**: All functionality must be accessible as a Python API
 
 ---
 
-## CLI usage
-
-Build MkDocs documentation:
-
-    doc-forge build --mkdocs --module my_package
-
-Build MCP documentation:
-
-    doc-forge build --mcp --module my_package
-
-Serve MkDocs locally:
-
-    doc-forge serve --module my_package
-
----
-
-## Public API
-
-Loaders:
-
-    GriffeLoader
-    discover_module_paths
-
-Renderers:
-
-    MkDocsRenderer
-    MCPRenderer
-
-CLI:
-
-    main
-
-Models:
-
-    models
-
----
-
-# Google-Styled Doc-Forge Convention (GSDFC)
-
-GSDFC defines how docstrings must be written so they render correctly in MkDocs and remain machine-parsable by doc-forge and AI tooling.
-
-- Docstrings are the single source of truth.
-- doc-forge compiles docstrings but does not generate documentation content.
-- Documentation follows the Python import hierarchy.
-- Every public symbol should have a complete and accurate docstring.
-
----
-
-## General rules
-
-- Use **Markdown headings** at package and module level.
-- Use **Google-style structured sections** at class, function, and method level.
-- Indent section contents using four spaces.
-- Use type hints in signatures instead of duplicating types in prose.
-- Write summaries in imperative form.
-- Sections are separated by ```---```
-
----
-
-## Package docstrings
-
-- Package docstrings act as the documentation home page.
-
-Recommended sections:
-
-    ## Summary
-    ## Installation
-    ## Quick start
-    ## Core concepts
-    ## Architecture
-    ## Rendering pipeline
-    ## CLI usage
-    ## Public API
-    ## Examples
-    ## Notes
-
-Example:
-    Package Doc String:
-
-        '''
-        Foo-bar processing framework.
-
-        Provides tools for defining Foo objects and executing Bar pipelines.
-
-        ---
-
-        # Installation
-
-            pip install foo-bar
-
-        ---
-
-        # Quick start
-
-            from foobar import Foo, BarEngine
-
-            foo = Foo("example")
-            engine = BarEngine([foo])
-
-            result = engine.run()
-
-        ---
-
-        # Public API
-
-            Foo
-            Bar
-            BarEngine
-
-        ---
-        '''
-
----
-
-## Module docstrings
-
-- Module docstrings describe a subsystem.
-
-Recommended sections:
-
-    ## Summary
-    ## Examples
-    ## Notes
-    ## Public API
-
-Example:
-    Module Doc String:
-
-        '''
-        Foo execution subsystem.
-
-        Provides utilities for executing Foo objects through Bar stages.
-
-        ---
-
-        Example:
-
-            from foobar.engine import BarEngine
-            from foobar.foo import Foo
-
-            foo = Foo("example")
-
-            engine = BarEngine([foo])
-            engine.run()
-
-        ---
-        '''
-
----
-
-## Class docstrings
-
-- Class docstrings define object responsibility, lifecycle, and attributes.
-
-Recommended sections:
-
-    Attributes:
-    Notes:
-    Example:
-    Raises:
-
-Example:
-    Simple Foo:
-
-        class Foo:
-            '''
-            Represents a unit of work.
-
-            Attributes:
-                name (str):
-                    Identifier of the foo instance.
-
-                value (int):
-                    Numeric value associated with foo.
-
-            Notes:
-                Guarantees:
-
-                    - instances are immutable after creation
-
-                Lifecycle:
-
-                    - create instance
-                    - pass to processing engine
-
-            Example:
-                Create and inspect a Foo:
-
-                    foo = Foo("example", value=42)
-                    print(foo.name)
-            '''
-
-    Complex Bar:
-
-        class BarEngine:
-            '''
-            Executes Foo objects through Bar stages.
-
-            Attributes:
-                foos (tuple[Foo, ...]):
-                    Foo instances managed by the engine.
-
-            Notes:
-                Guarantees:
-
-                    - deterministic execution order
-
-            Example:
-                Run engine:
-
-                    foo1 = Foo("a")
-                    foo2 = Foo("b")
-
-                    engine = BarEngine([foo1, foo2])
-                    engine.run()
-            '''
-
----
-
-## Function and method docstrings
-
-- Function docstrings define API contracts.
-
-Recommended sections:
-
-    Args:
-    Returns:
-    Raises:
-    Yields:
-    Notes:
-    Example:
-
-Example:
-    Simple process method:
-
-        def process(foo: Foo, multiplier: int) -> int:
-            '''
-            Process a Foo instance.
-
-            Args:
-                foo (Foo):
-                    Foo instance to process.
-
-                multiplier (int):
-                    Value used to scale foo.
-
-            Returns:
-                int:
-                    Processed result.
-
-            Raises:
-                ValueError:
-                    If multiplier is negative.
-
-            Notes:
-                Guarantees:
-
-                    - foo is not modified
-
-            Example:
-                Process foo:
-
-                    foo = Foo("example", value=10)
-
-                    result = process(foo, multiplier=2)
-                    print(result)
-            '''
-
-    Multiple Examples:
-
-        def combine(foo_a: Foo, foo_b: Foo) -> Foo:
-            '''
-            Combine two Foo instances.
-
-            Args:
-                foo_a (Foo):
-                    First foo.
-
-                foo_b (Foo):
-                    Second foo.
-
-            Returns:
-                Foo:
-                    Combined foo.
-
-            Example:
-                Basic usage:
-
-                    foo1 = Foo("a")
-                    foo2 = Foo("b")
-
-                    combined = combine(foo1, foo2)
-
-                Pipeline usage:
-
-                    engine = BarEngine([foo1, foo2])
-                    engine.run()
-            '''
-
----
-
-## Property docstrings
-
-- Properties must document return values.
-
-Example:
-    Property Doc String:
-
-        @property
-        def foos(self) -> tuple[Foo, ...]:
-            '''
-            Return contained Foo instances.
-
-            Returns:
-                tuple[Foo, ...]:
-                    Stored foo objects.
-
-            Example:
-                container = FooContainer()
-
-                foos = container.foos
-            '''
-
----
-
-## Attribute documentation
-
-- Document attributes in class docstrings using Attributes:.
-
-Example:
-    Attribute Doc String:
-
-        '''
-        Represents a processing stage.
-
-        Attributes:
-            id (str):
-                Unique identifier.
-
-            enabled (bool):
-                Whether the stage is active.
-        '''
-
----
-
-## Notes subsection grouping
-
-- Group related information using labeled subsections.
-
-Example:
-    Notes Example:
-
-        Notes:
-            **Guarantees:**
-
-                - deterministic behavior
-
-            **Lifecycle:**
-
-                - created during initialization
-                - reused across executions
-
-            **Thread safety:**
-
-                - safe for concurrent reads
-
----
-
-## Example formatting
-
-- Use indentation for examples.
-
-Example:
-    Single example:
-
-        Example:
-
-            foo = Foo("example")
-            process(foo, multiplier=2)
-
-    Multiple examples:
-
-        Example:
-            Create foo:
-
-                foo = Foo("example")
-
-            Run engine:
-
-                engine = BarEngine([foo])
-                engine.run()
-
-Avoid fenced code blocks inside structured sections.
-
----
-
-## Separator rules
-
-Use horizontal separators only at docstring root level to separate sections:
-
-    ---
-
-Allowed locations:
-
-- package docstrings
-- module docstrings
-- major documentation sections
-
-Do not use separators inside code sections.
-
----
-
-## Parsing guarantees
-
-GSDFC ensures doc-forge can deterministically extract:
-
-- symbol kind (module, class, function, property, attribute)
-- symbol name
-- parameters
-- return values
-- attributes
-- examples
-- structured Notes subsections
-
-This enables:
-
-- reliable MkDocs rendering
-- deterministic MCP export
-- accurate AI semantic interpretation
-
----
-
-Notes:
-    - doc-forge never executes analyzed modules.
-    - Documentation is generated entirely through static analysis.
+*doc-forge turns Python code into structured knowledge and emits it through multiple human and machine interfaces.*

docforge.nav.yml

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

docforge/__init__.py

@@ -1,536 +1,63 @@
 """
-Renderer-agnostic Python documentation compiler that converts Python docstrings
-into structured documentation for both humans (MkDocs) and machines (MCP / AI agents).
+# doc-forge
 
-`doc-forge` statically analyzes source code, builds a semantic model of modules,
-classes, functions, and attributes, and renders that model into documentation
-outputs without executing user code.
+`doc-forge` is a renderer-agnostic Python documentation compiler designed for
+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.
 
----
+## 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:
+Install using `pip` with the optional `mkdocs` dependencies for a complete setup:
 
-    pip install doc-forge
+```bash
+pip install doc-forge
+```
 
----
+## Quick Start
 
-## Quick start
-
-Generate a MkDocs site from a Python package:
-
-    doc-forge build --mkdocs --module my_package
-
-Generate MCP JSON documentation:
+1.  **Build Documentation**:
+    Introspect your package and generate documentation in one step:
+    ```bash
+    # Build MkDocs site
+    doc-forge build --mkdocs --module my_package --site-name "My Docs"
 
+    # Build MCP resources
     doc-forge build --mcp --module my_package
-
-Serve documentation locally:
-
-    doc-forge serve --mkdocs --module my_package
-
----
-
-## Core concepts
-
-**Loader**
-
-Extracts symbols, signatures, and docstrings using static analysis.
-
-**Semantic model**
-
-Structured, renderer-agnostic representation of the API.
-
-**Renderer**
-
-Converts the semantic model into output formats such as MkDocs or MCP JSON.
-
-**Symbol**
-
-Any documentable object:
-
-    - module
-    - class
-    - function
-    - method
-    - property
-    - attribute
-
----
-
-## Architecture
-
-`doc-forge` follows a compiler architecture:
-
-Front-end:
-
-    Static analysis of modules, classes, functions, type hints, and docstrings.
-
-Middle-end:
-
-    Builds a semantic model describing symbols and relationships.
-
-Back-end:
-
-    Renders documentation using interchangeable renderers.
-
-This architecture ensures deterministic documentation generation.
-
----
-
-## Rendering pipeline
-
-Typical flow:
-
-    Python package
-        ↓
-    Loader (static analysis)
-        ↓
-    Semantic model
-        ↓
-    Renderer
-        ↓
-    MkDocs site or MCP JSON
-
----
-
-## CLI usage
-
-Build MkDocs documentation:
-
-    doc-forge build --mkdocs --module my_package
-
-Build MCP documentation:
-
-    doc-forge build --mcp --module my_package
-
-Serve MkDocs locally:
-
-    doc-forge serve --module my_package
-
----
-
-## Public API
-
-Loaders:
-
-    GriffeLoader
-    discover_module_paths
-
-Renderers:
-
-    MkDocsRenderer
-    MCPRenderer
-
-CLI:
-
-    main
-
-Models:
-
-    models
-
----
-
-# Google-Styled Doc-Forge Convention (GSDFC)
-
-GSDFC defines how docstrings must be written so they render correctly in MkDocs and remain machine-parsable by doc-forge and AI tooling.
-
-- Docstrings are the single source of truth.
-- doc-forge compiles docstrings but does not generate documentation content.
-- Documentation follows the Python import hierarchy.
-- Every public symbol should have a complete and accurate docstring.
-
----
-
-## General rules
-
-- Use **Markdown headings** at package and module level.
-- Use **Google-style structured sections** at class, function, and method level.
-- Indent section contents using four spaces.
-- Use type hints in signatures instead of duplicating types in prose.
-- Write summaries in imperative form.
-- Sections are separated by ```---```
-
----
-
-## Package docstrings
-
-- Package docstrings act as the documentation home page.
-
-Recommended sections:
-
-    ## Summary
-    ## Installation
-    ## Quick start
-    ## Core concepts
-    ## Architecture
-    ## Rendering pipeline
-    ## CLI usage
-    ## Public API
-    ## Examples
-    ## Notes
-
-Example:
-    Package Doc String:
-
-        '''
-        Foo-bar processing framework.
-
-        Provides tools for defining Foo objects and executing Bar pipelines.
-
-        ---
-
-        # Installation
-
-            pip install foo-bar
-
-        ---
-
-        # Quick start
-
-            from foobar import Foo, BarEngine
-
-            foo = Foo("example")
-            engine = BarEngine([foo])
-
-            result = engine.run()
-
-        ---
-
-        # Public API
-
-            Foo
-            Bar
-            BarEngine
-
-        ---
-        '''
-
----
-
-## Module docstrings
-
-- Module docstrings describe a subsystem.
-
-Recommended sections:
-
-    ## Summary
-    ## Examples
-    ## Notes
-    ## Public API
-
-Example:
-    Module Doc String:
-
-        '''
-        Foo execution subsystem.
-
-        Provides utilities for executing Foo objects through Bar stages.
-
-        ---
-
-        Example:
-
-            from foobar.engine import BarEngine
-            from foobar.foo import Foo
-
-            foo = Foo("example")
-
-            engine = BarEngine([foo])
-            engine.run()
-
-        ---
-        '''
-
----
-
-## Class docstrings
-
-- Class docstrings define object responsibility, lifecycle, and attributes.
-
-Recommended sections:
-
-    Attributes:
-    Notes:
-    Example:
-    Raises:
-
-Example:
-    Simple Foo:
-
-        class Foo:
-            '''
-            Represents a unit of work.
-
-            Attributes:
-                name (str):
-                    Identifier of the foo instance.
-
-                value (int):
-                    Numeric value associated with foo.
-
-            Notes:
-                Guarantees:
-
-                    - instances are immutable after creation
-
-                Lifecycle:
-
-                    - create instance
-                    - pass to processing engine
-
-            Example:
-                Create and inspect a Foo:
-
-                    foo = Foo("example", value=42)
-                    print(foo.name)
-            '''
-
-    Complex Bar:
-
-        class BarEngine:
-            '''
-            Executes Foo objects through Bar stages.
-
-            Attributes:
-                foos (tuple[Foo, ...]):
-                    Foo instances managed by the engine.
-
-            Notes:
-                Guarantees:
-
-                    - deterministic execution order
-
-            Example:
-                Run engine:
-
-                    foo1 = Foo("a")
-                    foo2 = Foo("b")
-
-                    engine = BarEngine([foo1, foo2])
-                    engine.run()
-            '''
-
----
-
-## Function and method docstrings
-
-- Function docstrings define API contracts.
-
-Recommended sections:
-
-    Args:
-    Returns:
-    Raises:
-    Yields:
-    Notes:
-    Example:
-
-Example:
-    Simple process method:
-
-        def process(foo: Foo, multiplier: int) -> int:
-            '''
-            Process a Foo instance.
-
-            Args:
-                foo (Foo):
-                    Foo instance to process.
-
-                multiplier (int):
-                    Value used to scale foo.
-
-            Returns:
-                int:
-                    Processed result.
-
-            Raises:
-                ValueError:
-                    If multiplier is negative.
-
-            Notes:
-                Guarantees:
-
-                    - foo is not modified
-
-            Example:
-                Process foo:
-
-                    foo = Foo("example", value=10)
-
-                    result = process(foo, multiplier=2)
-                    print(result)
-            '''
-
-    Multiple Examples:
-
-        def combine(foo_a: Foo, foo_b: Foo) -> Foo:
-            '''
-            Combine two Foo instances.
-
-            Args:
-                foo_a (Foo):
-                    First foo.
-
-                foo_b (Foo):
-                    Second foo.
-
-            Returns:
-                Foo:
-                    Combined foo.
-
-            Example:
-                Basic usage:
-
-                    foo1 = Foo("a")
-                    foo2 = Foo("b")
-
-                    combined = combine(foo1, foo2)
-
-                Pipeline usage:
-
-                    engine = BarEngine([foo1, foo2])
-                    engine.run()
-            '''
-
----
-
-## Property docstrings
-
-- Properties must document return values.
-
-Example:
-    Property Doc String:
-
-        @property
-        def foos(self) -> tuple[Foo, ...]:
-            '''
-            Return contained Foo instances.
-
-            Returns:
-                tuple[Foo, ...]:
-                    Stored foo objects.
-
-            Example:
-                container = FooContainer()
-
-                foos = container.foos
-            '''
-
----
-
-## Attribute documentation
-
-- Document attributes in class docstrings using Attributes:.
-
-Example:
-    Attribute Doc String:
-
-        '''
-        Represents a processing stage.
-
-        Attributes:
-            id (str):
-                Unique identifier.
-
-            enabled (bool):
-                Whether the stage is active.
-        '''
-
----
-
-## Notes subsection grouping
-
-- Group related information using labeled subsections.
-
-Example:
-    Notes Example:
-
-        Notes:
-            **Guarantees:**
-
-                - deterministic behavior
-
-            **Lifecycle:**
-
-                - created during initialization
-                - reused across executions
-
-            **Thread safety:**
-
-                - safe for concurrent reads
-
----
-
-## Example formatting
-
-- Use indentation for examples.
-
-Example:
-    Single example:
-
-        Example:
-
-            foo = Foo("example")
-            process(foo, multiplier=2)
-
-    Multiple examples:
-
-        Example:
-            Create foo:
-
-                foo = Foo("example")
-
-            Run engine:
-
-                engine = BarEngine([foo])
-                engine.run()
-
-Avoid fenced code blocks inside structured sections.
-
----
-
-## Separator rules
-
-Use horizontal separators only at docstring root level to separate sections:
-
-    ---
-
-Allowed locations:
-
-- package docstrings
-- module docstrings
-- major documentation sections
-
-Do not use separators inside code sections.
-
----
-
-## Parsing guarantees
-
-GSDFC ensures doc-forge can deterministically extract:
-
-- symbol kind (module, class, function, property, attribute)
-- symbol name
-- parameters
-- return values
-- attributes
-- examples
-- structured Notes subsections
-
-This enables:
-
-- reliable MkDocs rendering
-- deterministic MCP export
-- accurate AI semantic interpretation
-
----
-
-Notes:
-    - doc-forge never executes analyzed modules.
-    - Documentation is generated entirely through static analysis.
+    ```
+
+2.  **Define Navigation**:
+    Create a `docforge.nav.yml` to organize your documentation:
+    ```yaml
+    home: my_package/index.md
+    groups:
+      Core API:
+        - my_package/core/*.md
+      Utilities:
+        - my_package/utils.md
+    ```
+
+3.  **Preview**:
+    ```bash
+    # Serve MkDocs site
+    doc-forge serve --mkdocs
+
+    # Serve MCP documentation
+    doc-forge serve --mcp
+    ```
+
+## Project Structure
+
+- `docforge.loaders`: Introspects source code using static analysis (`griffe`).
+- `docforge.models`: The internal representation of your project, modules, and objects.
+- `docforge.renderers`: Converters that turn the models into physical files.
+- `docforge.nav`: Managers for logical-to-physical path mapping and navigation.
 """
 
 from .loaders import GriffeLoader, discover_module_paths

docforge/cli/__init__.py

@@ -1,31 +1,14 @@
 """
-Command line interface entry point for doc-forge.
+# CLI Layer
 
-This module exposes the primary CLI entry function used by the
-``doc-forge`` command. The actual command implementation resides in
-``docforge.cli.main``, while this module provides a stable import path
-for external tools and the package entry point configuration.
+The `docforge.cli` package provides the command-line interface for interacting
+with doc-forge.
 
-The CLI is responsible for orchestrating documentation workflows such as
-generating renderer sources, building documentation sites, exporting
-machine-readable documentation bundles, and starting development or MCP
-servers.
+## Available Commands
 
----
-
-Typical usage
--------------
-
-The CLI is normally invoked through the installed command:
-
-    doc-forge <command> [options]
-
-Programmatic invocation is also possible:
-
-    from docforge.cli import main
-    main()
-
----
+- **build**: Build documentation (MkDocs site or MCP resources).
+- **serve**: Serve documentation (MkDocs or MCP).
+- **tree**: Visualize the introspected project structure.
 """
 
 from .main import main

docforge/cli/commands.py

@@ -9,10 +9,8 @@ from docforge.cli import mcp_utils
 @click.group()
 def cli() -> None:
     """
-    Root command group for the doc-forge CLI.
-
-    Provides commands for building, serving, and inspecting
-    documentation generated from Python source code.
+    doc-forge CLI: A tool for introspecting Python projects and generating
+    documentation.
     """
     pass
 
@@ -20,20 +18,20 @@ def cli() -> None:
 @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("--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
 @click.option("--out-dir", type=click.Path(path_type=Path), default=Path("mcp_docs"), help="MCP output directory")
 def build(
     mcp: bool,
     mkdocs: bool,
-    module_is_source: bool,
     module: Optional[str],
     project_name: Optional[str],
     site_name: Optional[str],
@@ -44,36 +42,24 @@ def build(
     out_dir: Path,
 ) -> None:
     """
-    Build documentation artifacts.
+    Build documentation (MkDocs site or MCP resources).
 
-    This command performs the full documentation build pipeline:
-
-    1. Introspects the Python project using Griffe
-    2. Generates renderer-specific documentation sources
-    3. Optionally builds the final documentation output
-
-    Depending on the selected options, the build can target:
-
-    - MkDocs static documentation sites
-    - MCP structured documentation 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: Enable MCP documentation generation.
-        mkdocs: Enable MkDocs documentation generation.
-        module_is_source: Treat the specified module directory as the
-            project root.
-        module: Python module import path to document.
+        mcp: Use the MCP documentation builder.
+        mkdocs: Use the MkDocs documentation builder.
+        module: The dotted path of the module to document.
         project_name: Optional override for the project name.
-        site_name: Display name for the MkDocs site.
-        docs_dir: Directory where Markdown documentation sources
-            will be generated.
-        nav_file: Path to the navigation specification file.
-        template: Optional custom MkDocs configuration template.
-        mkdocs_yml: Output path for the generated MkDocs configuration.
-        out_dir: Output directory for generated MCP resources.
-
-    Raises:
-        click.UsageError: If required options are missing or conflicting.
+        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")
@@ -85,12 +71,7 @@ def build(
             site_name = module
 
         click.echo(f"Generating MkDocs sources in {docs_dir}...")
-        mkdocs_utils.generate_sources(
-            module,
-            docs_dir,
-            project_name,
-            module_is_source,
-        )
+        mkdocs_utils.generate_sources(module, project_name, docs_dir)
 
         click.echo(f"Generating MkDocs config {mkdocs_yml}...")
         mkdocs_utils.generate_config(docs_dir, nav_file, template, mkdocs_yml, site_name)
@@ -111,74 +92,58 @@ def build(
 @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 generated documentation locally.
-
-    Depending on the selected mode, this command starts either:
-
-    - A MkDocs development server for browsing documentation
-    - An MCP server exposing structured documentation resources
+    Serve documentation (MkDocs or MCP).
 
     Args:
-        mcp: Serve documentation using the MCP server.
-        mkdocs: Serve the MkDocs development site.
-        module: Python module import path to serve via MCP.
-        mkdocs_yml: Path to the MkDocs configuration file.
-        out_dir: Root directory containing MCP documentation resources.
-
-    Raises:
-        click.UsageError: If invalid or conflicting options are provided.
+        mcp: Serve MCP resources via an MCP server.
+        mkdocs: Serve the MkDocs site using the built-in development server.
+        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_utils.serve(mkdocs_yml)
     elif mcp:
-        mcp_utils.serve(module, out_dir)
+        mcp_utils.serve(out_dir)
 
 
 @cli.command()
 @click.option(
-    "--module",
+    "--modules",
+    multiple=True,
     required=True,
-    help="Python module import path to introspect",
+    help="Python module import paths to introspect",
 )
 @click.option(
     "--project-name",
-    help="Project name (defaults to specified module)",
+    help="Project name (defaults to first module)",
 )
 def tree(
-    module: str,
+    modules: Sequence[str],
     project_name: Optional[str],
 ) -> None:
     """
-    Display the documentation object tree for a module.
-
-    This command introspects the specified module and prints a
-    hierarchical representation of the discovered documentation
-    objects, including modules, classes, functions, and members.
+    Visualize the project structure in the terminal.
 
     Args:
-        module: Python module import path to introspect.
-        project_name: Optional name to display as the project root.
+        modules: List of module import paths to recursively introspect.
+        project_name: Optional override for the project name shown at the root.
     """
     loader = GriffeLoader()
-    project = loader.load_project([module], project_name)
+    project = loader.load_project(list(modules), project_name)
 
     click.echo(project.name)
 
@@ -190,14 +155,11 @@ def tree(
 
 def _print_object(obj, indent: str) -> None:
     """
-    Recursively print a documentation object and its members.
-
-    This helper function traverses the documentation object graph
-    and prints each object with indentation to represent hierarchy.
+    Recursive helper to print doc objects and their members to the console.
 
     Args:
-        obj: Documentation object to print.
-        indent: Current indentation prefix used for nested members.
+        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

@@ -7,7 +7,6 @@ cli: Group
 def build(
     mcp: bool,
     mkdocs: bool,
-    module_is_source: bool,
     module: Optional[str],
     project_name: Optional[str],
     site_name: Optional[str],
@@ -21,13 +20,12 @@ def build(
 def serve(
     mcp: bool,
     mkdocs: bool,
-    module: Optional[str],
     mkdocs_yml: Path,
     out_dir: Path,
 ) -> None: ...
 
 def tree(
-    module: str,
+    modules: Sequence[str],
     project_name: Optional[str],
 ) -> None: ...
 

docforge/cli/main.py

@@ -1,23 +1,14 @@
 """
-Command-line entry point for the doc-forge CLI.
-
-This module exposes the executable entry point that initializes the
-Click command group defined in ``docforge.cli.commands``.
+Main entry point for the doc-forge CLI. This module delegates all command
+execution to docforge.cli.commands.
 """
-
 from docforge.cli.commands import cli
 
-
 def main() -> None:
     """
-    Run the doc-forge command-line interface.
-
-    This function initializes and executes the Click CLI application.
-    It is used as the console entry point when invoking ``doc-forge``
-    from the command line.
+    CLI Entry point. Boots the click application.
     """
     cli()
 
-
 if __name__ == "__main__":
     main()

docforge/cli/mcp_utils.py

@@ -4,22 +4,14 @@ from docforge.loaders import GriffeLoader, discover_module_paths
 from docforge.renderers import MCPRenderer
 from docforge.servers import MCPServer
 
-
 def generate_resources(module: str, project_name: str | None, out_dir: Path) -> None:
     """
-    Generate MCP documentation resources from a Python module.
-
-    The function performs project introspection, builds the internal
-    documentation model, and renders MCP-compatible JSON resources
-    to the specified output directory.
+    Generate MCP-compatible documentation resources.
 
     Args:
-        module: Python module import path used as the entry point for
-            documentation generation.
-        project_name: Optional override for the project name used in
-            generated documentation metadata.
-        out_dir: Directory where MCP resources (index.json, nav.json,
-            and module data) will be written.
+        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)
@@ -28,23 +20,12 @@ def generate_resources(module: str, project_name: str | None, out_dir: Path) ->
     renderer = MCPRenderer()
     renderer.generate_sources(project, out_dir)
 
-
-def serve(module: str, mcp_root: Path) -> None:
+def serve(mcp_root: Path) -> None:
     """
-    Start an MCP server for a pre-generated documentation bundle.
-
-    The server exposes documentation resources such as project metadata,
-    navigation structure, and module documentation through MCP endpoints.
+    Serve MCP documentation from a pre-built bundle.
 
     Args:
-        module: Python module import path used to identify the served
-            documentation instance.
-        mcp_root: Path to the directory containing the MCP documentation
-            bundle (index.json, nav.json, and modules/).
-
-    Raises:
-        click.ClickException: If the MCP documentation bundle is missing
-            required files or directories.
+        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}")
@@ -61,6 +42,6 @@ def serve(module: str, mcp_root: Path) -> None:
 
     server = MCPServer(
         mcp_root=mcp_root,
-        name=f"{module}-mcp",
+        name="doc-forge-mcp",
     )
     server.run()

docforge/cli/mcp_utils.pyi

@@ -1,4 +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: ...
+def serve(mcp_root: Path) -> None: ...

docforge/cli/mkdocs_utils.py

@@ -6,73 +6,32 @@ 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,
-    docs_dir: Path,
-    project_name: str | None = None,
-    module_is_source: bool | None = None,
-) -> None:
+def generate_sources(module: str, project_name: str | None, docs_dir: Path) -> None:
     """
-    Generate MkDocs Markdown sources for a Python module.
-
-    This function introspects the specified module, builds the internal
-    documentation model, and renders Markdown documentation files for
-    use with MkDocs.
+    Generate Markdown source files for the specified module.
 
     Args:
-        module: Python module import path used as the entry point for
-            documentation generation.
+        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.
-        project_name: Optional override for the project name used in
-            documentation metadata.
-        module_is_source: If True, treat the specified module directory as
-            the project root rather than a nested module.
     """
     loader = GriffeLoader()
     discovered_paths = discover_module_paths(module)
     project = loader.load_project(discovered_paths, project_name)
 
     renderer = MkDocsRenderer()
-    renderer.generate_sources(
-        project,
-        docs_dir,
-        module_is_source,
-    )
+    renderer.generate_sources(project, docs_dir)
 
-    renderer.generate_readme(
-        project,
-        docs_dir,
-        module_is_source,
-    )
-
-
-def generate_config(
-    docs_dir: Path,
-    nav_file: Path,
-    template: Path | None,
-    out: Path,
-    site_name: str,
-) -> None:
+def generate_config(docs_dir: Path, nav_file: Path, template: Path | None, out: Path, site_name: str) -> None:
     """
-    Generate an ``mkdocs.yml`` configuration file.
-
-    The configuration is created by combining a template configuration
-    with a navigation structure derived from the docforge navigation
-    specification.
+    Generate an mkdocs.yml configuration file.
 
     Args:
-        docs_dir: Directory containing generated documentation Markdown files.
-        nav_file: Path to the ``docforge.nav.yml`` navigation specification.
-        template: Optional path to a custom MkDocs configuration template.
-            If not provided, a built-in template will be used.
-        out: Destination path where the generated ``mkdocs.yml`` file
-            will be written.
-        site_name: Display name for the generated documentation site.
-
-    Raises:
-        click.FileError: If the navigation specification or template
-            file cannot be found.
+        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")
@@ -99,19 +58,12 @@ def generate_config(
 
     out.write_text(yaml.safe_dump(data, sort_keys=False), encoding="utf-8")
 
-
 def build(mkdocs_yml: Path) -> None:
     """
-    Build the MkDocs documentation site.
-
-    This function loads the MkDocs configuration and runs the MkDocs
-    build command to generate the final static documentation site.
+    Build the documentation site using MkDocs.
 
     Args:
-        mkdocs_yml: Path to the ``mkdocs.yml`` configuration file.
-
-    Raises:
-        click.ClickException: If the configuration file does not exist.
+        mkdocs_yml: Path to the mkdocs.yml configuration file.
     """
     if not mkdocs_yml.exists():
         raise click.ClickException(f"mkdocs.yml not found: {mkdocs_yml}")
@@ -121,19 +73,12 @@ def build(mkdocs_yml: Path) -> None:
 
     mkdocs_build(load_config(str(mkdocs_yml)))
 
-
 def serve(mkdocs_yml: Path) -> None:
     """
-    Start an MkDocs development server with live reload.
-
-    The server watches documentation files and automatically reloads
-    the site when changes are detected.
+    Serve the documentation site with live-reload using MkDocs.
 
     Args:
-        mkdocs_yml: Path to the ``mkdocs.yml`` configuration file.
-
-    Raises:
-        click.ClickException: If the configuration file does not exist.
+        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

@@ -1,11 +1,6 @@
 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_sources(module: str, project_name: str | None, docs_dir: Path) -> 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/loaders/__init__.py

@@ -1,27 +1,17 @@
 """
-Loader layer for doc-forge.
+# Loader Layer
 
-The ``docforge.loaders`` package is responsible for discovering Python modules
-and extracting documentation data using static analysis.
+The `docforge.loaders` package is responsible for discovering Python source files
+and extracting their documentation using static analysis.
 
----
+## Core Features
 
-Overview
---------
-
-This layer converts Python source code into an intermediate documentation
-model used by doc-forge. It performs module discovery, introspection, and
-initial filtering before the data is passed to the core documentation models.
-
-Core capabilities include:
-
-- **Module discovery** – Locate Python modules and packages within a project.
-- **Static introspection** – Parse docstrings, signatures, and object
-  hierarchies using the ``griffe`` library without executing the code.
-- **Public API filtering** – Exclude private members (names prefixed with
-  ``_``) to produce clean public documentation structures.
-
----
+- **Discovery**: Automatically find all modules and packages in a project
+  directory.
+- **Introspection**: Uses `griffe` to parse docstrings, signatures, and
+  hierarchical relationships without executing the code.
+- **Filtering**: Automatically excludes private members (prefixed with `_`) to
+  ensure clean public documentation.
 """
 
 from .griffe_loader import GriffeLoader, discover_module_paths

docforge/loaders/griffe_loader.py

@@ -1,9 +1,6 @@
 """
-Utilities for loading and introspecting Python modules using Griffe.
-
-This module provides the ``GriffeLoader`` class and helper utilities used to
-discover Python modules, introspect their structure, and convert the results
-into doc-forge documentation models.
+This module provides the GriffeLoader, which uses the 'griffe' library to
+introspect Python source code and populate the doc-forge Project models.
 """
 
 import logging
@@ -28,27 +25,19 @@ def discover_module_paths(
     project_root: Path | None = None,
 ) -> List[str]:
     """
-    Discover Python modules within a package directory.
+    Discover all Python modules under a package via filesystem traversal.
 
-    The function scans the filesystem for ``.py`` files inside the specified
-    package and converts them into dotted module import paths.
-
-    Discovery rules:
-
-    - Directories containing ``__init__.py`` are treated as packages.
-    - Each ``.py`` file is treated as a module.
-    - Results are returned as dotted import paths.
+    Rules:
+    - Directory with __init__.py is treated as a package.
+    - Any .py file is treated as a module.
+    - All paths are converted to dotted module paths.
 
     Args:
-        module_name: Top-level package name to discover modules from.
-        project_root: Root directory used to resolve module paths. If not
-            provided, the current working directory is used.
+        module_name: The name of the package to discover.
+        project_root: The root directory of the project. Defaults to current working directory.
 
     Returns:
-        A sorted list of unique dotted module import paths.
-
-    Raises:
-        FileNotFoundError: If the specified package directory does not exist.
+        A sorted list of dotted module paths.
     """
 
     if project_root is None:
@@ -75,19 +64,12 @@ def discover_module_paths(
 
 class GriffeLoader:
     """
-    Load Python modules using Griffe and convert them into doc-forge models.
-
-    This loader uses the Griffe introspection engine to analyze Python source
-    code and transform the extracted information into ``Project``, ``Module``,
-    and ``DocObject`` instances used by doc-forge.
+    Loads Python modules and extracts documentation using the Griffe introspection engine.
     """
 
     def __init__(self) -> None:
         """
-        Initialize the Griffe-backed loader.
-
-        Creates an internal Griffe loader instance with dedicated collections
-        for modules and source lines.
+        Initialize the GriffeLoader.
         """
         self._loader = _GriffeLoader(
             modules_collection=ModulesCollection(),
@@ -95,32 +77,21 @@ class GriffeLoader:
         )
 
     def load_project(
-            self,
-            module_paths: List[str],
-            project_name: Optional[str] = None,
-            skip_import_errors: bool = None,
+        self,
+        module_paths: List[str],
+        project_name: Optional[str] = None,
+        skip_import_errors: bool = None,
     ) -> Project:
         """
-        Load multiple modules and assemble them into a Project model.
-
-        Each module path is introspected and converted into a ``Module``
-        instance. All modules are then aggregated into a single ``Project``
-        object.
+        Load multiple modules and combine them into a single Project models.
 
         Args:
-            module_paths: List of dotted module import paths to load.
-            project_name: Optional override for the project name. Defaults
-                to the top-level name of the first module.
-            skip_import_errors: If True, modules that fail to load will be
-                skipped instead of raising an error.
+            module_paths: A list of dotted paths to the modules to load.
+            project_name: Optional name for the project. Defaults to the first module name.
+            skip_import_errors: If True, modules that fail to import will be skipped.
 
         Returns:
-            A populated ``Project`` instance containing the loaded modules.
-
-        Raises:
-            ValueError: If no module paths are provided.
-            ImportError: If a module fails to load and
-                ``skip_import_errors`` is False.
+            A Project instance containing the loaded modules.
         """
         if not module_paths:
             raise ValueError("At least one module path must be provided")
@@ -145,16 +116,13 @@ class GriffeLoader:
 
     def load_module(self, path: str) -> Module:
         """
-        Load and convert a single Python module.
-
-        The module is introspected using Griffe and then transformed into
-        a doc-forge ``Module`` model.
+        Load a single module and convert its introspection data into the docforge models.
 
         Args:
-            path: Dotted import path of the module.
+            path: The dotted path of the module to load.
 
         Returns:
-            A populated ``Module`` instance.
+            A Module instance.
         """
         self._loader.load(path)
         griffe_module = self._loader.modules_collection[path]
@@ -167,16 +135,13 @@ class GriffeLoader:
 
     def _convert_module(self, obj: Object) -> Module:
         """
-        Convert a Griffe module object into a doc-forge Module.
-
-        All public members of the module are recursively converted into
-        ``DocObject`` instances.
+        Convert a Griffe Object (module) into a docforge Module.
 
         Args:
-            obj: Griffe object representing the module.
+            obj: The Griffe Object representing the module.
 
         Returns:
-            A populated ``Module`` model.
+            A populated Module instance.
         """
         module = Module(
             path=obj.path,
@@ -193,17 +158,13 @@ class GriffeLoader:
 
     def _convert_object(self, obj: Object) -> DocObject:
         """
-        Convert a Griffe object into a doc-forge DocObject.
-
-        The conversion preserves the object's metadata such as name,
-        kind, path, signature, and docstring. Child members are processed
-        recursively.
+        Recursively convert a Griffe Object into a DocObject hierarchy.
 
         Args:
-            obj: Griffe object representing a documented Python object.
+            obj: The Griffe Object to convert.
 
         Returns:
-            A ``DocObject`` instance representing the converted object.
+            A DocObject instance.
         """
         kind = obj.kind.value
         signature = self._safe_signature(obj)
@@ -232,13 +193,13 @@ class GriffeLoader:
 
     def _safe_docstring(self, obj: Object) -> Optional[str]:
         """
-        Safely extract a docstring from a Griffe object.
+        Safely retrieve the docstring value from a Griffe object.
 
         Args:
-            obj: Griffe object to inspect.
+            obj: The Griffe Object to inspect.
 
         Returns:
-            The raw docstring text if available, otherwise ``None``.
+            The raw docstring string, or None if missing or unresolvable.
         """
         try:
             return obj.docstring.value if obj.docstring else None
@@ -247,14 +208,13 @@ class GriffeLoader:
 
     def _safe_signature(self, obj: Object) -> Optional[str]:
         """
-        Safely extract the signature of a Griffe object.
+        Safely retrieve the signature string from a Griffe object.
 
         Args:
-            obj: Griffe object to inspect.
+            obj: The Griffe Object to inspect.
 
         Returns:
-            String representation of the object's signature if available,
-            otherwise ``None``.
+            The string representation of the signature, or None.
         """
         try:
             if hasattr(obj, "signature") and obj.signature:

docforge/models/__init__.py

@@ -1,32 +1,17 @@
 """
-Model layer for doc-forge.
+# Model Layer
 
-The ``docforge.models`` package defines the core data structures used to
-represent Python source code as a structured documentation model.
+The `docforge.models` package provides the core data structures used to represent
+Python source code in a documentation-focused hierarchy.
 
----
+## Key Components
 
-Overview
---------
+- **Project**: The root container for all documented modules.
+- **Module**: Represents a Python module or package, containing members.
+- **DocObject**: A recursive structure for classes, functions, and attributes.
 
-The model layer forms the central intermediate representation used throughout
-doc-forge. Python modules and objects discovered during introspection are
-converted into a hierarchy of documentation models that can later be rendered
-into different documentation formats.
-
-Key components:
-
-- **Project** – Root container representing an entire documented codebase.
-- **Module** – Representation of a Python module or package containing
-  documented members.
-- **DocObject** – Recursive structure representing Python objects such as
-  classes, functions, methods, and attributes.
-
-These models are intentionally **renderer-agnostic**, allowing the same
-documentation structure to be transformed into multiple output formats
-(e.g., MkDocs, MCP, or other renderers).
-
----
+These classes are designed to be renderer-agnostic, allowing the same internal
+representation to be transformed into various output formats (currently MkDocs).
 """
 
 from .project import Project

docforge/models/module.py

@@ -1,10 +1,7 @@
 """
-Documentation model representing a Python module or package.
-
-This module defines the ``Module`` class used in the doc-forge documentation
-model. A ``Module`` acts as a container for top-level documented objects
-(classes, functions, variables, and other members) discovered during
-introspection.
+This module defines the Module class, which represents a Python module or package
+in the doc-forge documentation models. It acts as a container for top-level
+documented objects.
 """
 
 from typing import Dict, Iterable, Optional
@@ -14,17 +11,12 @@ from docforge.models.object import DocObject
 
 class Module:
     """
-    Representation of a documented Python module or package.
-
-    A ``Module`` stores metadata about the module itself and maintains a
-    collection of top-level documentation objects discovered during
-    introspection.
+    Represents a documented Python module or package.
 
     Attributes:
         path: Dotted import path of the module.
-        docstring: Module-level documentation string, if present.
-        members: Mapping of object names to their corresponding
-            ``DocObject`` representations.
+        docstring: Module-level docstring content.
+        members: Dictionary mapping object names to their DocObject representations.
     """
 
     def __init__(
@@ -33,11 +25,11 @@ class Module:
         docstring: Optional[str] = None,
     ) -> None:
         """
-        Initialize a Module instance.
+        Initialize a new Module.
 
         Args:
-            path: Dotted import path identifying the module.
-            docstring: Module-level documentation text, if available.
+            path: The dotted path of the module.
+            docstring: The module's docstring, if any.
         """
         self.path = path
         self.docstring = docstring
@@ -48,32 +40,27 @@ class Module:
         Add a documented object to the module.
 
         Args:
-            obj: Documentation object to register as a top-level
-                member of the module.
+            obj: The object to add.
         """
         self.members[obj.name] = obj
 
     def get_object(self, name: str) -> DocObject:
         """
-        Retrieve a documented object by name.
+        Retrieve a member object by name.
 
         Args:
-            name: Name of the object to retrieve.
+            name: The name of the object.
 
         Returns:
-            The corresponding ``DocObject`` instance.
-
-        Raises:
-            KeyError: If no object with the given name exists.
+            The requested DocObject.
         """
         return self.members[name]
 
     def get_all_objects(self) -> Iterable[DocObject]:
         """
-        Return all top-level documentation objects in the module.
+        Get all top-level objects in the module.
 
         Returns:
-            An iterable of ``DocObject`` instances representing the
-            module's public members.
+            An iterable of DocObject instances.
         """
         return self.members.values()

docforge/models/object.py

@@ -1,10 +1,7 @@
 """
-Documentation model representing individual Python objects.
-
-This module defines the ``DocObject`` class, the fundamental recursive unit of
-the doc-forge documentation model. Each ``DocObject`` represents a Python
-entity such as a class, function, method, or attribute, and may contain nested
-members that form a hierarchical documentation structure.
+This module defines the DocObject class, the fundamental recursive unit of the
+doc-forge documentation models. A DocObject represents a single Python entity
+(class, function, method, or attribute) and its nested members.
 """
 
 from typing import Dict, Iterable, Optional
@@ -12,20 +9,15 @@ from typing import Dict, Iterable, Optional
 
 class DocObject:
     """
-    Representation of a documented Python object.
-
-    A ``DocObject`` models a single Python entity discovered during
-    introspection. Objects may contain nested members, allowing the structure
-    of modules, classes, and other containers to be represented recursively.
+    Represents a documented Python object (class, function, method, etc.).
 
     Attributes:
         name: Local name of the object.
-        kind: Type of object (for example ``class``, ``function``,
-            ``method``, or ``attribute``).
-        path: Fully qualified dotted path to the object.
-        signature: Callable signature if the object represents a callable.
-        docstring: Raw docstring text extracted from the source code.
-        members: Mapping of member names to child ``DocObject`` instances.
+        kind: Type of object (e.g., 'class', 'function', 'attribute').
+        path: Full dotted import path to the object.
+        signature: Callable signature, if applicable.
+        docstring: Raw docstring content extracted from the source.
+        members: Dictionary mapping member names to their DocObject representations.
     """
 
     def __init__(
@@ -37,54 +29,48 @@ class DocObject:
         docstring: Optional[str] = None,
     ) -> None:
         """
-        Initialize a DocObject instance.
+        Initialize a new DocObject.
 
         Args:
-            name: Local name of the object.
-            kind: Object type identifier (for example ``class`` or ``function``).
-            path: Fully qualified dotted path of the object.
-            signature: Callable signature if applicable.
-            docstring: Documentation string associated with the object.
+            name: The local name of the object.
+            kind: The kind of object (e.g., 'class', 'function').
+            path: The full dotted path to the object.
+            signature: The object's signature (for callable objects).
+            docstring: The object's docstring, if any.
         """
         self.name = name
         self.kind = kind
         self.path = path
         self.signature = signature
         self.docstring = docstring
-        self.members: Dict[str, "DocObject"] = {}
+        self.members: Dict[str, 'DocObject'] = {}
 
-    def add_member(self, obj: "DocObject") -> None:
+    def add_member(self, obj: 'DocObject') -> None:
         """
-        Add a child documentation object.
-
-        This is typically used when attaching methods to classes or
-        nested objects to their parent containers.
+        Add a child member to this object (e.g., a method to a class).
 
         Args:
-            obj: Documentation object to add as a member.
+            obj: The child DocObject to add.
         """
         self.members[obj.name] = obj
 
-    def get_member(self, name: str) -> "DocObject":
+    def get_member(self, name: str) -> 'DocObject':
         """
-        Retrieve a member object by name.
+        Retrieve a child member by name.
 
         Args:
-            name: Name of the member to retrieve.
+            name: The name of the member.
 
         Returns:
-            The corresponding ``DocObject`` instance.
-
-        Raises:
-            KeyError: If the member does not exist.
+            The requested DocObject.
         """
         return self.members[name]
 
-    def get_all_members(self) -> Iterable["DocObject"]:
+    def get_all_members(self) -> Iterable['DocObject']:
         """
-        Return all child members of the object.
+        Get all members of this object.
 
         Returns:
-            An iterable of ``DocObject`` instances representing nested members.
+            An iterable of child DocObject instances.
         """
         return self.members.values()

docforge/models/project.py

@@ -1,9 +1,6 @@
 """
-Documentation model representing a project.
-
-This module defines the ``Project`` class, the top-level container used by
-doc-forge to represent a documented codebase. A ``Project`` aggregates multiple
-modules and provides access to them through a unified interface.
+This module defines the Project class, the top-level container for a documented
+project. It aggregates multiple Module instances into a single named entity.
 """
 
 from typing import Dict, Iterable
@@ -13,32 +10,29 @@ from docforge.models.module import Module
 
 class Project:
     """
-    Representation of a documentation project.
-
-    A ``Project`` serves as the root container for all modules discovered during
-    introspection. Each module is stored by its dotted import path.
+    Represents a documentation project, serving as a container for modules.
 
     Attributes:
         name: Name of the project.
-        modules: Mapping of module paths to ``Module`` instances.
+        modules: Dictionary mapping module paths to Module instances.
     """
 
     def __init__(self, name: str) -> None:
         """
-        Initialize a Project instance.
+        Initialize a new Project.
 
         Args:
-            name: Name used to identify the documentation project.
+            name: The name of the project.
         """
         self.name = name
         self.modules: Dict[str, Module] = {}
 
     def add_module(self, module: Module) -> None:
         """
-        Register a module in the project.
+        Add a module to the project.
 
         Args:
-            module: Module instance to add to the project.
+            module: The module to add.
         """
         self.modules[module.path] = module
 
@@ -47,30 +41,27 @@ class Project:
         Retrieve a module by its dotted path.
 
         Args:
-            path: Fully qualified dotted module path (for example ``pkg.module``).
+            path: The dotted path of the module (e.g., 'pkg.mod').
 
         Returns:
-            The corresponding ``Module`` instance.
-
-        Raises:
-            KeyError: If the module does not exist in the project.
+            The requested Module.
         """
         return self.modules[path]
 
     def get_all_modules(self) -> Iterable[Module]:
         """
-        Return all modules contained in the project.
+        Get all modules in the project.
 
         Returns:
-            An iterable of ``Module`` instances.
+            An iterable of Module objects.
         """
         return self.modules.values()
 
     def get_module_list(self) -> list[str]:
         """
-        Return the list of module import paths.
+        Get the list of all module dotted paths.
 
         Returns:
-            A list containing the dotted paths of all modules in the project.
+            A list of module paths.
         """
         return list(self.modules.keys())

docforge/nav/__init__.py

@@ -1,26 +1,17 @@
 """
-Navigation layer for doc-forge.
+# Navigation Layer
 
-The ``docforge.nav`` package manages the relationship between the logical
-documentation structure defined by the user and the physical documentation
-files generated on disk.
+The `docforge.nav` package manages the mapping between the logical documentation
+structure and the physical files on disk.
 
----
+## Workflow
 
-Workflow
---------
+1.  **Spec Definition**: Users define navigation intent in `docforge.nav.yml`.
+2.  **Resolution**: `resolve_nav` matches patterns in the spec to generated `.md` files.
+3.  **Emission**: `MkDocsNavEmitter` produces the final YAML structure for `mkdocs.yml`.
 
-1. **Specification** – Users define navigation intent in ``docforge.nav.yml``.
-2. **Resolution** – ``resolve_nav`` expands patterns and matches them against
-   generated Markdown files.
-3. **Emission** – ``MkDocsNavEmitter`` converts the resolved structure into
-   the YAML navigation format required by ``mkdocs.yml``.
-
-This layer separates documentation organization from the underlying source
-code layout, enabling flexible grouping, ordering, and navigation structures
-independent of module hierarchy.
-
----
+This abstraction allows doc-forge to support complex grouping and ordering
+independently of the source code's physical layout.
 """
 
 from .spec import NavSpec, load_nav_spec

docforge/nav/mkdocs.py

@@ -1,9 +1,7 @@
 """
-MkDocs navigation emitter.
-
-This module provides the ``MkDocsNavEmitter`` class, which converts a
-``ResolvedNav`` instance into the navigation structure required by the
-MkDocs ``nav`` configuration.
+This module provides the MkDocsNavEmitter, which converts a ResolvedNav instance
+into the specific YAML-ready list structure expected by the MkDocs 'nav'
+configuration.
 """
 
 from pathlib import Path
@@ -14,24 +12,19 @@ from docforge.nav.resolver import ResolvedNav
 
 class MkDocsNavEmitter:
     """
-    Emit MkDocs navigation structures from resolved navigation data.
-
-    The emitter transforms a ``ResolvedNav`` object into the YAML-compatible
-    list structure expected by the MkDocs ``nav`` configuration field.
+    Emitter responsible for transforming a ResolvedNav into an MkDocs-compatible
+    navigation structure.
     """
 
     def emit(self, nav: ResolvedNav) -> List[Dict[str, Any]]:
         """
-        Generate a navigation structure for ``mkdocs.yml``.
+        Generate a list of navigation entries for mkdocs.yml.
 
         Args:
-            nav: Resolved navigation data describing documentation groups
-                and their associated Markdown files.
+            nav: The resolved navigation data.
 
         Returns:
-            A list of dictionaries representing the MkDocs navigation layout.
-            Each dictionary maps a navigation label to a page or a list of
-            pages.
+            A list of dictionary mappings representing the MkDocs navigation.
         """
         result: List[Dict[str, Any]] = []
 
@@ -52,18 +45,16 @@ class MkDocsNavEmitter:
 
     def _to_relative(self, path: Path, docs_root: Path | None) -> str:
         """
-        Convert a filesystem path into a documentation-relative path.
-
-        This method normalizes paths so they can be used in MkDocs navigation.
-        It handles both absolute and relative filesystem paths and ensures the
-        resulting path is relative to the documentation root.
+        Convert a filesystem path to a path relative to the documentation root.
+        This handles both absolute and relative filesystem paths, ensuring the
+        output is compatible with MkDocs navigation requirements.
 
         Args:
-            path: Filesystem path to convert.
-            docs_root: Root directory of the documentation sources.
+            path: The path to convert.
+            docs_root: The root directory for documentation.
 
         Returns:
-            POSIX-style path relative to the documentation root.
+            A string representing the relative POSIX-style path.
         """
         if docs_root and path.is_absolute():
             try:

docforge/nav/resolver.py

@@ -1,8 +1,7 @@
 """
-Navigation resolution utilities.
-
-This module resolves a ``NavSpec`` against the filesystem by expanding glob
-patterns and validating that referenced documentation files exist.
+This module contains the logic for resolving a NavSpec against the physical
+filesystem. It expands globs and validates that all referenced documents
+actually exist on disk.
 """
 
 from pathlib import Path
@@ -15,15 +14,12 @@ from docforge.nav.spec import NavSpec
 
 class ResolvedNav:
     """
-    Resolved navigation structure.
-
-    A ``ResolvedNav`` represents navigation data after glob patterns have been
-    expanded and paths validated against the filesystem.
+    Represents a navigation structure where all patterns and paths have been
+    resolved against the actual filesystem contents.
 
     Attributes:
-        home: Relative path to the documentation home page.
-        groups: Mapping of navigation group titles to lists of resolved
-            documentation file paths.
+        home: Resolved relative path to the home page.
+        groups: Mapping of group titles to lists of absolute or relative Path objects.
     """
 
     def __init__(
@@ -36,9 +32,9 @@ class ResolvedNav:
         Initialize a ResolvedNav instance.
 
         Args:
-            home: Relative path to the home page within the documentation root.
-            groups: Mapping of group titles to resolved documentation file paths.
-            docs_root: Root directory of the documentation source files.
+            home: The relative path to the project home page.
+            groups: A mapping of group names to their resolved filesystem paths.
+            docs_root: The root documentation directory.
         """
         self.home = home
         self.groups = groups
@@ -46,20 +42,15 @@ class ResolvedNav:
 
     def all_files(self) -> Iterable[Path]:
         """
-        Iterate over all files referenced by the navigation structure.
+        Get an iterable of all resolved files in the navigation structure.
 
         Returns:
-            An iterable of ``Path`` objects representing documentation files.
-
-        Raises:
-            RuntimeError: If the home page is defined but the documentation
-                root is not available for resolution.
+            An iterable of Path objects.
         """
         if self.home:
             if self._docs_root is None:
                 raise RuntimeError("docs_root is required to resolve home path")
             yield self._docs_root / self.home
-
         for paths in self.groups.values():
             for p in paths:
                 yield p
@@ -70,37 +61,34 @@ def resolve_nav(
     docs_root: Path,
 ) -> ResolvedNav:
     """
-    Resolve a navigation specification against the filesystem.
-
-    The function expands glob patterns defined in a ``NavSpec`` and verifies
-    that referenced documentation files exist within the documentation root.
+    Create a ResolvedNav by processing a NavSpec against the filesystem.
+    This expands globs and validates the existence of referenced files.
 
     Args:
-        spec: Navigation specification describing documentation layout.
-        docs_root: Root directory containing documentation Markdown files.
+        spec: The navigation specification to resolve.
+        docs_root: The root directory for documentation files.
 
     Returns:
-        A ``ResolvedNav`` instance containing validated navigation paths.
+        A ResolvedNav instance.
 
     Raises:
-        FileNotFoundError: If the documentation root does not exist or a
-            navigation pattern does not match any files.
+        FileNotFoundError: If a pattern doesn't match any files or the docs_root doesn't exist.
     """
     if not docs_root.exists():
         raise FileNotFoundError(docs_root)
 
     def resolve_pattern(pattern: str) -> List[Path]:
         """
-        Resolve a glob pattern relative to the documentation root.
+        Resolve a single glob pattern relative to the docs_root.
 
         Args:
-            pattern: Glob pattern used to match documentation files.
+            pattern: The glob pattern to resolve.
 
         Returns:
-            A sorted list of matching ``Path`` objects.
+            A sorted list of matching Path objects.
 
         Raises:
-            FileNotFoundError: If the pattern does not match any files.
+            FileNotFoundError: If the pattern doesn't match any files.
         """
         full = docs_root / pattern
         matches = sorted(
@@ -112,7 +100,7 @@ def resolve_nav(
 
         return matches
 
-    # Resolve home page
+    # Resolve home
     home: str | None = None
     if spec.home:
         home_path = docs_root / spec.home
@@ -120,7 +108,7 @@ def resolve_nav(
             raise FileNotFoundError(spec.home)
         home = spec.home
 
-    # Resolve navigation groups
+    # Resolve groups
     resolved_groups: Dict[str, List[Path]] = {}
 
     for group, patterns in spec.groups.items():

docforge/nav/spec.py

@@ -1,9 +1,7 @@
 """
-Navigation specification model.
-
-This module defines the ``NavSpec`` class, which represents the navigation
-structure defined by the user in the doc-forge navigation specification
-(typically ``docforge.nav.yml``).
+This module defines the NavSpec class, which represents the user's intent for
+documentation navigation as defined in a YAML specification (usually
+docforge.nav.yml).
 """
 
 from pathlib import Path
@@ -14,16 +12,11 @@ import yaml
 
 class NavSpec:
     """
-    Parsed representation of a navigation specification.
-
-    A ``NavSpec`` describes the intended documentation navigation layout before
-    it is resolved against the filesystem.
+    Parsed representation of the docforge navigation specification file.
 
     Attributes:
-        home: Relative path to the documentation home page (for example
-            ``index.md``).
-        groups: Mapping of navigation group titles to lists of file patterns
-            or glob expressions.
+        home: Path to the home document (e.g., 'index.md').
+        groups: Mapping of group titles to lists of path patterns/globs.
     """
 
     def __init__(
@@ -32,12 +25,11 @@ class NavSpec:
         groups: Dict[str, List[str]],
     ) -> None:
         """
-        Initialize a NavSpec instance.
+        Initialize a NavSpec.
 
         Args:
-            home: Relative path to the home document.
-            groups: Mapping of group names to lists of path patterns
-                (glob expressions).
+            home: The path to the home document.
+            groups: A mapping of group names to lists of path patterns (globs).
         """
         self.home = home
         self.groups = groups
@@ -45,18 +37,17 @@ class NavSpec:
     @classmethod
     def load(cls, path: Path) -> "NavSpec":
         """
-        Load a navigation specification from a YAML file.
+        Load a NavSpec from a YAML file.
 
         Args:
-            path: Filesystem path to the navigation specification file.
+            path: The filesystem path to the YAML file.
 
         Returns:
-            A ``NavSpec`` instance representing the parsed configuration.
+            A NavSpec instance.
 
         Raises:
-            FileNotFoundError: If the specified file does not exist.
-            ValueError: If the file contents are not a valid navigation
-                specification.
+            FileNotFoundError: If the path does not exist.
+            ValueError: If the file content is not a valid NavSpec mapping.
         """
         if not path.exists():
             raise FileNotFoundError(path)
@@ -87,45 +78,33 @@ class NavSpec:
 
     def all_patterns(self) -> List[str]:
         """
-        Return all path patterns referenced by the specification.
+        Get all path patterns referenced in the specification.
 
         Returns:
-            A list containing the home document (if defined) and all
-            group pattern entries.
+            A list of all patterns (home plus all groups).
         """
         patterns: List[str] = []
-
         if self.home:
             patterns.append(self.home)
-
         for items in self.groups.values():
             patterns.extend(items)
-
         return patterns
 
 
 def load_nav_spec(path: Path) -> NavSpec:
     """
-    Load a navigation specification file.
-
-    This helper function reads a YAML navigation file and constructs a
-    corresponding ``NavSpec`` instance.
+    Utility function to load a NavSpec from a file.
 
     Args:
         path: Path to the navigation specification file.
 
     Returns:
-        A ``NavSpec`` instance representing the parsed specification.
-
-    Raises:
-        FileNotFoundError: If the specification file does not exist.
-        ValueError: If the YAML structure is invalid.
+        A loaded NavSpec instance.
     """
     if not path.exists():
         raise FileNotFoundError(path)
 
     data = yaml.safe_load(path.read_text(encoding="utf-8"))
-
     if not isinstance(data, dict):
         raise ValueError("Nav spec must be a YAML mapping")
 

docforge/renderers/__init__.py

@@ -1,34 +1,20 @@
 """
-Renderers layer for doc-forge.
+# Renderers Layer
 
-The ``docforge.renderers`` package transforms the internal documentation
-models into files formatted for specific documentation systems.
+The `docforge.renderers` package handles the transformation of the internal
+documentation models into physical files formatted for specific documentation
+engines.
 
----
+## Current Implementations
 
-Overview
---------
+- **MkDocsRenderer**: Generates Markdown files utilizing the `mkdocstrings`
+  syntax. It automatically handles package/module hierarchy and generates
+  `index.md` files for packages.
 
-Renderers consume the doc-forge project model and generate output suitable
-for documentation tools or machine interfaces.
+## Extending
 
-Current implementations:
-
-- **MkDocsRenderer** – Produces Markdown files compatible with MkDocs and
-  the ``mkdocstrings`` plugin. It automatically handles package hierarchy
-  and generates ``index.md`` files for packages.
-- **MCPRenderer** – Emits structured JSON resources designed for consumption
-  by Model Context Protocol (MCP) clients.
-
----
-
-Extending
----------
-
-New renderers can be added by implementing the ``DocRenderer`` protocol
-defined in ``docforge.renderers.base``.
-
----
+To add a new renderer, implement the `DocRenderer` protocol defined in
+`docforge.renderers.base`.
 """
 
 from .mkdocs_renderer import MkDocsRenderer

docforge/renderers/base.py

@@ -1,9 +1,7 @@
 """
-Renderer base interfaces and configuration models.
-
-This module defines the base protocol and configuration container used by
-doc-forge renderers. Concrete renderer implementations should implement the
-``DocRenderer`` protocol.
+This module defines the base interfaces and configuration containers for
+doc-forge renderers. All renderer implementations should adhere to the
+DocRenderer protocol.
 """
 
 from pathlib import Path
@@ -16,22 +14,12 @@ class RendererConfig:
     """
     Configuration container for documentation renderers.
 
-    A ``RendererConfig`` instance groups together the project model and the
-    output directory used during rendering.
-
-    Attributes:
-        out_dir: Directory where generated documentation files will be written.
-        project: Documentation project model to be rendered.
+    Args:
+        out_dir: The directory where documentation files should be written.
+        project: The introspected project models to be rendered.
     """
 
     def __init__(self, out_dir: Path, project: Project) -> None:
-        """
-        Initialize a RendererConfig instance.
-
-        Args:
-            out_dir: Target directory where documentation files should be written.
-            project: Introspected project model to render.
-        """
         self.out_dir = out_dir
         self.project = project
 
@@ -39,9 +27,6 @@ class RendererConfig:
 class DocRenderer(Protocol):
     """
     Protocol defining the interface for documentation renderers.
-
-    Implementations of this protocol are responsible for transforming a
-    ``Project`` model into renderer-specific documentation sources.
     """
 
     name: str
@@ -52,11 +37,10 @@ class DocRenderer(Protocol):
         out_dir: Path,
     ) -> None:
         """
-        Generate renderer-specific documentation sources.
+        Generate renderer-specific source files for the given project.
 
         Args:
-            project: Project model containing modules and documentation objects.
-            out_dir: Directory where generated documentation sources
-                should be written.
+            project: The project models containing modules and objects.
+            out_dir: Target directory for the generated files.
         """
         ...

docforge/renderers/mcp_renderer.py

@@ -7,25 +7,18 @@ from docforge.models import Project, Module, DocObject
 
 class MCPRenderer:
     """
-    Renderer that generates MCP-compatible documentation resources.
-
-    This renderer converts doc-forge project models into structured JSON
-    resources suitable for consumption by systems implementing the Model
-    Context Protocol (MCP).
+    Renderer that emits MCP-native JSON resources from docforge models.
     """
 
     name = "mcp"
 
     def generate_sources(self, project: Project, out_dir: Path) -> None:
         """
-        Generate MCP documentation resources for a project.
-
-        The renderer serializes each module into a JSON resource and produces
-        supporting metadata files such as ``nav.json`` and ``index.json``.
+        Generate MCP-compatible JSON resources and navigation for the project.
 
         Args:
-            project: Documentation project model to render.
-            out_dir: Directory where MCP resources will be written.
+            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)
@@ -61,11 +54,11 @@ class MCPRenderer:
 
     def _write_module(self, module: Module, modules_dir: Path) -> None:
         """
-        Serialize a module into an MCP resource file.
+        Serialize a module into an MCP JSON resource on disk.
 
         Args:
-            module: Module instance to serialize.
-            modules_dir: Directory where module JSON files are stored.
+            module: The module instance to serialize.
+            modules_dir: The directory where the module JSON file should be written.
         """
         payload = {
             "module": module.path,
@@ -78,13 +71,13 @@ class MCPRenderer:
 
     def _render_module(self, module: Module) -> Dict:
         """
-        Convert a Module model into MCP-compatible structured data.
+        Render a Module into MCP-friendly structured data.
 
         Args:
-            module: Module instance to convert.
+            module: The module instance to render.
 
         Returns:
-            Dictionary representing the module and its documented objects.
+            A dictionary following the MCP documentation resource schema.
         """
         data: Dict = {
             "path": module.path,
@@ -99,13 +92,13 @@ class MCPRenderer:
 
     def _render_object(self, obj: DocObject) -> Dict:
         """
-        Recursively convert a DocObject into structured MCP data.
+        Recursively render a DocObject into structured MCP data.
 
         Args:
-            obj: Documentation object to convert.
+            obj: The documented object (class, func, etc.) to render.
 
         Returns:
-            Dictionary describing the object and any nested members.
+            A dictionary representing the object and its members.
         """
         data: Dict = {
             "name": obj.name,
@@ -126,13 +119,4 @@ class MCPRenderer:
 
     @staticmethod
     def _json(data: Dict) -> str:
-        """
-        Serialize data to formatted JSON.
-
-        Args:
-            data: Dictionary to serialize.
-
-        Returns:
-            JSON string formatted with indentation and UTF-8 compatibility.
-        """
         return json.dumps(data, indent=2, ensure_ascii=False)

docforge/renderers/mkdocs_renderer.py

@@ -1,272 +1,91 @@
 """
-MkDocs renderer implementation.
-
-This module defines the ``MkDocsRenderer`` class, which generates Markdown
-documentation sources compatible with MkDocs Material and the mkdocstrings
-plugin.
-
-The renderer ensures a consistent documentation structure by:
-
-- Creating a root ``index.md`` if one does not exist
-- Generating package index pages automatically
-- Linking child modules within parent package pages
-- Optionally generating ``README.md`` from the root package docstring
+This module implements the MkDocsRenderer, which generates Markdown source files
+compatible with the MkDocs 'material' theme and 'mkdocstrings' extension.
 """
 
 from pathlib import Path
-from docforge.models import Project, Module
+
+from docforge.models import Project
 
 
 class MkDocsRenderer:
     """
-    Renderer that produces Markdown documentation for MkDocs.
-
-    Generated pages use mkdocstrings directives to reference Python modules,
-    allowing MkDocs to render API documentation dynamically.
+    Renderer that generates Markdown source files formatted for the MkDocs
+    'mkdocstrings' plugin.
     """
 
     name = "mkdocs"
 
-    # -------------------------
-    # Public API
-    # -------------------------
-
-    def generate_sources(
-        self,
-        project: Project,
-        out_dir: Path,
-        module_is_source: bool | None = None,
-    ) -> None:
+    def generate_sources(self, project: Project, out_dir: Path) -> None:
         """
-        Generate Markdown documentation files for a project.
-
-        This method renders a documentation structure from the provided
-        project model and writes the resulting Markdown files to the
-        specified output directory.
+        Produce a set of Markdown files in the output directory based on the
+        provided Project models.
 
         Args:
-            project: Project model containing modules to document.
-            out_dir: Directory where generated Markdown files will be written.
-            module_is_source: If True, treat the specified module as the
-                documentation root rather than nesting it inside a folder.
+            project: The project models to render.
+            out_dir: Target directory for documentation files.
         """
-        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}
 
-        # Detect packages (modules with children)
+        # Package detection (level-agnostic)
         packages = {
             p for p in paths
             if any(other.startswith(p + ".") for other in paths)
         }
 
         for module in modules:
-            self._write_module(
-                module,
-                packages,
-                out_dir,
-                module_is_source,
-            )
-
-    def generate_readme(
-        self,
-        project: Project,
-        docs_dir: Path,
-        module_is_source: bool | None = None,
-    ) -> None:
-        """
-        Generate a ``README.md`` file from the root module docstring.
-
-        Behavior:
-
-        - If ``module_is_source`` is True, ``README.md`` is written to the
-          project root directory.
-        - If False, README generation is currently not implemented.
-
-        Args:
-            project: Project model containing documentation metadata.
-            docs_dir: Directory containing generated documentation sources.
-            module_is_source: Whether the module is treated as the project
-                source root.
-        """
-
-        if not module_is_source:
-            # Future: support README generation per module
-            return
-
-        readme_path = docs_dir.parent / "README.md"
-
-        root_module = None
-        for module in project.get_all_modules():
-            if module.path == project.name:
-                root_module = module
-                break
-
-        if root_module is None:
-            return
-
-        doc = ""
-
-        if root_module.docstring:
-            doc = getattr(
-                root_module.docstring,
-                "value",
-                str(root_module.docstring),
-            )
-
-        content = (
-            f"# {project.name}\n\n"
-            f"{doc.strip()}\n"
-        )
-
-        if not readme_path.exists() or readme_path.read_text(encoding="utf-8") != content:
-            readme_path.write_text(
-                content,
-                encoding="utf-8",
-            )
+            self._write_module(module, packages, out_dir)
 
     # -------------------------
     # Internal helpers
     # -------------------------
-
-    def _find_root_module(self, project: Project) -> Module | None:
+    def _write_module(self, module, packages: set[str], out_dir: Path) -> None:
         """
-        Locate the root module corresponding to the project name.
+        Write a single module's documentation file. Packages are written as
+        'index.md' inside their respective directories.
 
         Args:
-            project: Project model to inspect.
-
-        Returns:
-            The root ``Module`` if found, otherwise ``None``.
+            module: The module to write.
+            packages: A set of module paths that are identified as packages.
+            out_dir: The base output directory.
         """
-        for module in project.get_all_modules():
-            if module.path == project.name:
-                return module
-        return None
-
-    def _write_module(
-        self,
-        module: Module,
-        packages: set[str],
-        out_dir: Path,
-        module_is_source: bool | None = None,
-    ) -> None:
-        """
-        Write documentation for a single module.
-
-        Package modules are rendered as ``index.md`` files inside their
-        corresponding directories, while leaf modules are written as
-        standalone Markdown pages.
-
-        Args:
-            module: Module to render.
-            packages: Set of module paths identified as packages.
-            out_dir: Base directory for generated documentation files.
-            module_is_source: Whether the module acts as the documentation
-                root directory.
-        """
-
         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
             dir_path = out_dir.joinpath(*parts)
             dir_path.mkdir(parents=True, exist_ok=True)
 
             md_path = dir_path / "index.md"
-            link_target = f"{parts[-1]}/" if parts else None
+            title = parts[-1].replace("_", " ").title()
         else:
+            # leaf module → <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"
-            link_target = f"{parts[-1]}.md" if parts else None
+            title = parts[-1].replace("_", " ").title()
 
-        title = parts[-1].replace("_", " ").title() if parts else module_name
         content = self._render_markdown(title, module.path)
 
-        if not md_path.exists() or md_path.read_text(encoding="utf-8") != content:
-            md_path.write_text(content, encoding="utf-8")
+        if md_path.exists() and md_path.read_text(encoding="utf-8") == content:
+            return
 
-        if not module_is_source:
-            self._ensure_parent_index(parts, out_dir, link_target, title)
+        md_path.write_text(content, encoding="utf-8")
 
     def _render_markdown(self, title: str, module_path: str) -> str:
         """
-        Generate Markdown content for a module documentation page.
+        Generate the Markdown content for a module file.
 
         Args:
-            title: Page title displayed in the documentation.
-            module_path: Dotted import path of the module.
+            title: The display title for the page.
+            module_path: The dotted path of the module to document.
 
         Returns:
-            Markdown source containing a mkdocstrings directive.
+            A string containing the Markdown source.
         """
         return (
             f"# {title}\n\n"
             f"::: {module_path}\n"
         )
-
-    def _ensure_root_index(
-        self,
-        project: Project,
-        out_dir: Path,
-    ) -> None:
-        """
-        Ensure that the root ``index.md`` page exists.
-
-        Args:
-            project: Project model used for the page title.
-            out_dir: Documentation output directory.
-        """
-        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:
-        """
-        Ensure that parent package index files exist and contain links to
-        child modules.
-
-        Args:
-            parts: Module path components.
-            out_dir: Documentation output directory.
-            link_target: Link target used in the parent index.
-            title: Display title for the link.
-        """
-        if len(parts) == 1:
-            parent_index = out_dir / "index.md"
-        else:
-            parent_dir = out_dir.joinpath(*parts[:-1])
-            parent_dir.mkdir(parents=True, exist_ok=True)
-            parent_index = parent_dir / "index.md"
-
-            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")
-
-        link = f"- [{title}]({link_target})\n"
-        if link not in content:
-            parent_index.write_text(content + link, encoding="utf-8")

docforge/renderers/mkdocs_renderer.pyi

@@ -1,34 +1,17 @@
 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,
-        module_is_source: bool | None = None,
-    ) -> None: ...
-
-    def generate_readme(
-        self,
-        project: Project,
-        docs_dir: Path,
-        module_is_source: bool | None = None,
-    ) -> None:
-
+    def generate_sources(self, project: Project, out_dir: Path) -> 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: ...

docforge/servers/__init__.py

@@ -1,13 +1,3 @@
-"""
-Server layer for doc-forge.
-
-This module exposes server implementations used to provide live access
-to generated documentation resources. Currently, it includes the MCP
-documentation server.
-
----
-"""
-
 from .mcp_server import MCPServer
 
 __all__ = [

docforge/servers/mcp_server.py

@@ -9,21 +9,16 @@ from mcp.server.fastmcp import FastMCP
 
 class MCPServer:
     """
-    MCP server for serving a pre-generated documentation bundle.
-
-    The server exposes documentation resources and diagnostic tools through
-    MCP endpoints backed by JSON files generated by the MCP renderer.
+    MCP server for serving a pre-built MCP documentation bundle.
     """
 
     def __init__(self, mcp_root: Path, name: str) -> None:
         """
-        Initialize the MCP server.
+        Initialize the MCPServer.
 
         Args:
-            mcp_root: Directory containing the generated MCP documentation
-                bundle (for example ``index.json``, ``nav.json``, and
-                ``modules/``).
-            name: Identifier used for the MCP server instance.
+            mcp_root: Path to the directory containing pre-built MCP JSON resources.
+            name: Name of the MCP server.
         """
         self.mcp_root = mcp_root
         self.app = FastMCP(name)
@@ -37,24 +32,19 @@ class MCPServer:
 
     def _read_json(self, path: Path) -> Any:
         """
-        Load and parse a JSON file.
-
-        If the file does not exist, a structured error response is returned
-        instead of raising an exception.
+        Read and parse a JSON file, returning diagnostic errors if missing.
 
         Args:
-            path: Path to the JSON file to read.
+            path: Path to the JSON file.
 
         Returns:
-            Parsed JSON data if the file exists, otherwise an error dictionary
-            describing the missing resource.
+            The parsed JSON data or an error dictionary.
         """
         if not path.exists():
             return {
                 "error": "not_found",
                 "path": str(path),
             }
-
         return json.loads(path.read_text(encoding="utf-8"))
 
     # ------------------------------------------------------------------
@@ -63,16 +53,8 @@ class MCPServer:
 
     def _register_resources(self) -> None:
         """
-        Register MCP resource endpoints.
-
-        The server exposes documentation resources through the following
-        endpoints:
-
-        - ``docs://index`` – Project metadata
-        - ``docs://nav`` – Navigation structure
-        - ``docs://modules/{module}`` – Individual module documentation
+        Register MCP resources for index, nav, and individual modules.
         """
-
         @self.app.resource("docs://index")
         def index():
             return self._read_json(self.mcp_root / "index.json")
@@ -88,35 +70,26 @@ class MCPServer:
             )
 
     # ------------------------------------------------------------------
-    # MCP tools
+    # MCP tools (optional / diagnostic)
     # ------------------------------------------------------------------
 
     def _register_tools(self) -> None:
         """
-        Register optional MCP diagnostic tools.
-
-        These tools provide lightweight endpoints useful for verifying that
-        the MCP server is operational.
+        Register high-level MCP tools for diagnostics.
         """
-
         @self.app.tool()
         def ping() -> str:
-            """Return a simple health check response."""
             return "pong"
 
     # ------------------------------------------------------------------
     # Server lifecycle
     # ------------------------------------------------------------------
 
-    def run(
-        self,
-        transport: Literal["stdio", "sse", "streamable-http"] = "streamable-http",
-    ) -> None:
+    def run(self, transport: Literal["stdio", "sse", "streamable-http"] = "streamable-http") -> None:
         """
         Start the MCP server.
 
         Args:
-            transport: Transport mechanism used by the MCP server. Supported
-                options include ``stdio``, ``sse``, and ``streamable-http``.
+            transport: MCP transport (default: streamable-http)
         """
         self.app.run(transport=transport)

docforge/templates/mkdocs.sample.yml

@@ -4,30 +4,16 @@ theme:
     - scheme: slate
       primary: deep purple
       accent: cyan
-
   font:
     text: Inter
     code: JetBrains Mono
-
   features:
-    # Navigation
-    - navigation.sections
+    - navigation.tabs
     - navigation.expand
     - navigation.top
     - navigation.instant
-    - navigation.tracking
-    - navigation.indexes
-
-    # Content
     - content.code.copy
     - content.code.annotate
-    - content.tabs.link
-    - content.action.edit
-
-    # Search UX
-    - search.highlight
-    - search.share
-    - search.suggest
 
 plugins:
   - search
@@ -45,34 +31,3 @@ plugins:
             annotations_path: brief
             show_root_heading: true
             group_by_category: true
-            show_category_heading: true
-            show_object_full_path: false
-            show_symbol_type_heading: true
-
-markdown_extensions:
-  - pymdownx.superfences
-  - pymdownx.inlinehilite
-  - pymdownx.snippets
-
-  - admonition
-  - pymdownx.details
-
-  - pymdownx.superfences
-  - pymdownx.highlight:
-      linenums: true
-      anchor_linenums: true
-      line_spans: __span
-      pygments_lang_class: true
-
-  - pymdownx.tabbed:
-      alternate_style: true
-
-  - pymdownx.tasklist:
-      custom_checkbox: true
-
-  - tables
-  - footnotes
-
-  - pymdownx.caret
-  - pymdownx.tilde
-  - pymdownx.mark

docs/docforge/index.md

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

mcp_docs/modules/docforge.cli.commands.json

@@ -37,21 +37,21 @@
         "kind": "class",
         "path": "docforge.cli.commands.GriffeLoader",
         "signature": "<bound method Alias.signature of Alias('GriffeLoader', 'docforge.loaders.GriffeLoader')>",
-        "docstring": "Load Python modules using Griffe and convert them into doc-forge models.\n\nThis loader uses the Griffe introspection engine to analyze Python source\ncode and transform the extracted information into ``Project``, ``Module``,\nand ``DocObject`` instances used by doc-forge.",
+        "docstring": "Loads Python modules and extracts documentation using the Griffe introspection engine.",
         "members": {
           "load_project": {
             "name": "load_project",
             "kind": "function",
             "path": "docforge.cli.commands.GriffeLoader.load_project",
             "signature": "<bound method Alias.signature of Alias('load_project', 'docforge.loaders.griffe_loader.GriffeLoader.load_project')>",
-            "docstring": "Load multiple modules and assemble them into a Project model.\n\nEach module path is introspected and converted into a ``Module``\ninstance. All modules are then aggregated into a single ``Project``\nobject.\n\nArgs:\n    module_paths: List of dotted module import paths to load.\n    project_name: Optional override for the project name. Defaults\n        to the top-level name of the first module.\n    skip_import_errors: If True, modules that fail to load will be\n        skipped instead of raising an error.\n\nReturns:\n    A populated ``Project`` instance containing the loaded modules.\n\nRaises:\n    ValueError: If no module paths are provided.\n    ImportError: If a module fails to load and\n        ``skip_import_errors`` is False."
+            "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.GriffeLoader.load_module",
             "signature": "<bound method Alias.signature of Alias('load_module', 'docforge.loaders.griffe_loader.GriffeLoader.load_module')>",
-            "docstring": "Load and convert a single Python module.\n\nThe module is introspected using Griffe and then transformed into\na doc-forge ``Module`` model.\n\nArgs:\n    path: Dotted import path of the module.\n\nReturns:\n    A populated ``Module`` instance."
+            "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."
           }
         }
       },
@@ -95,21 +95,21 @@
             "kind": "class",
             "path": "docforge.cli.commands.mkdocs_utils.GriffeLoader",
             "signature": "<bound method Alias.signature of Alias('GriffeLoader', 'docforge.cli.mkdocs_utils.GriffeLoader')>",
-            "docstring": "Load Python modules using Griffe and convert them into doc-forge models.\n\nThis loader uses the Griffe introspection engine to analyze Python source\ncode and transform the extracted information into ``Project``, ``Module``,\nand ``DocObject`` instances used by doc-forge.",
+            "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_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 assemble them into a Project model.\n\nEach module path is introspected and converted into a ``Module``\ninstance. All modules are then aggregated into a single ``Project``\nobject.\n\nArgs:\n    module_paths: List of dotted module import paths to load.\n    project_name: Optional override for the project name. Defaults\n        to the top-level name of the first module.\n    skip_import_errors: If True, modules that fail to load will be\n        skipped instead of raising an error.\n\nReturns:\n    A populated ``Project`` instance containing the loaded modules.\n\nRaises:\n    ValueError: If no module paths are provided.\n    ImportError: If a module fails to load and\n        ``skip_import_errors`` is False."
+                "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_utils.GriffeLoader.load_module",
                 "signature": "<bound method Alias.signature of Alias('load_module', 'docforge.loaders.griffe_loader.GriffeLoader.load_module')>",
-                "docstring": "Load and convert a single Python module.\n\nThe module is introspected using Griffe and then transformed into\na doc-forge ``Module`` model.\n\nArgs:\n    path: Dotted import path of the module.\n\nReturns:\n    A populated ``Module`` instance."
+                "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."
               }
             }
           },
@@ -118,14 +118,14 @@
             "kind": "function",
             "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 Python modules within a package directory.\n\nThe function scans the filesystem for ``.py`` files inside the specified\npackage and converts them into dotted module import paths.\n\nDiscovery rules:\n\n- Directories containing ``__init__.py`` are treated as packages.\n- Each ``.py`` file is treated as a module.\n- Results are returned as dotted import paths.\n\nArgs:\n    module_name: Top-level package name to discover modules from.\n    project_root: Root directory used to resolve module paths. If not\n        provided, the current working directory is used.\n\nReturns:\n    A sorted list of unique dotted module import paths.\n\nRaises:\n    FileNotFoundError: If the specified package directory does not exist."
+            "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_utils.MkDocsRenderer",
             "signature": "<bound method Alias.signature of Alias('MkDocsRenderer', 'docforge.cli.mkdocs_utils.MkDocsRenderer')>",
-            "docstring": "Renderer that produces Markdown documentation for MkDocs.\n\nGenerated pages use mkdocstrings directives to reference Python modules,\nallowing MkDocs to render API documentation dynamically.",
+            "docstring": "Renderer that generates Markdown source files formatted for the MkDocs\n'mkdocstrings' plugin.",
             "members": {
               "name": {
                 "name": "name",
@@ -139,14 +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": "Generate Markdown documentation files for a project.\n\nThis method renders a documentation structure from the provided\nproject model and writes the resulting Markdown files to the\nspecified output directory.\n\nArgs:\n    project: Project model containing modules to document.\n    out_dir: Directory where generated Markdown files will be written.\n    module_is_source: If True, treat the specified module as the\n        documentation root rather than nesting it inside a folder."
-              },
-              "generate_readme": {
-                "name": "generate_readme",
-                "kind": "function",
-                "path": "docforge.cli.commands.mkdocs_utils.MkDocsRenderer.generate_readme",
-                "signature": "<bound method Alias.signature of Alias('generate_readme', 'docforge.renderers.mkdocs_renderer.MkDocsRenderer.generate_readme')>",
-                "docstring": "Generate a ``README.md`` file from the root module docstring.\n\nBehavior:\n\n- If ``module_is_source`` is True, ``README.md`` is written to the\n  project root directory.\n- If False, README generation is currently not implemented.\n\nArgs:\n    project: Project model containing documentation metadata.\n    docs_dir: Directory containing generated documentation sources.\n    module_is_source: Whether the module is treated as the project\n        source root."
+                "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."
               }
             }
           },
@@ -155,28 +148,28 @@
             "kind": "function",
             "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": "Load a navigation specification file.\n\nThis helper function reads a YAML navigation file and constructs a\ncorresponding ``NavSpec`` instance.\n\nArgs:\n    path: Path to the navigation specification file.\n\nReturns:\n    A ``NavSpec`` instance representing the parsed specification.\n\nRaises:\n    FileNotFoundError: If the specification file does not exist.\n    ValueError: If the YAML structure is invalid."
+            "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_utils.resolve_nav",
             "signature": "<bound method Alias.signature of Alias('resolve_nav', 'docforge.cli.mkdocs_utils.resolve_nav')>",
-            "docstring": "Resolve a navigation specification against the filesystem.\n\nThe function expands glob patterns defined in a ``NavSpec`` and verifies\nthat referenced documentation files exist within the documentation root.\n\nArgs:\n    spec: Navigation specification describing documentation layout.\n    docs_root: Root directory containing documentation Markdown files.\n\nReturns:\n    A ``ResolvedNav`` instance containing validated navigation paths.\n\nRaises:\n    FileNotFoundError: If the documentation root does not exist or a\n        navigation pattern does not match any files."
+            "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_utils.MkDocsNavEmitter",
             "signature": "<bound method Alias.signature of Alias('MkDocsNavEmitter', 'docforge.cli.mkdocs_utils.MkDocsNavEmitter')>",
-            "docstring": "Emit MkDocs navigation structures from resolved navigation data.\n\nThe emitter transforms a ``ResolvedNav`` object into the YAML-compatible\nlist structure expected by the MkDocs ``nav`` configuration field.",
+            "docstring": "Emitter responsible for transforming a ResolvedNav into an MkDocs-compatible\nnavigation structure.",
             "members": {
               "emit": {
                 "name": "emit",
                 "kind": "function",
                 "path": "docforge.cli.commands.mkdocs_utils.MkDocsNavEmitter.emit",
                 "signature": "<bound method Alias.signature of Alias('emit', 'docforge.nav.mkdocs.MkDocsNavEmitter.emit')>",
-                "docstring": "Generate a navigation structure for ``mkdocs.yml``.\n\nArgs:\n    nav: Resolved navigation data describing documentation groups\n        and their associated Markdown files.\n\nReturns:\n    A list of dictionaries representing the MkDocs navigation layout.\n    Each dictionary maps a navigation label to a page or a list of\n    pages."
+                "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."
               }
             }
           },
@@ -185,28 +178,28 @@
             "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 MkDocs Markdown sources for a Python module.\n\nThis function introspects the specified module, builds the internal\ndocumentation model, and renders Markdown documentation files for\nuse with MkDocs.\n\nArgs:\n    module: Python module import path used as the entry point for\n        documentation generation.\n    docs_dir: Directory where the generated Markdown files will be written.\n    project_name: Optional override for the project name used in\n        documentation metadata.\n    module_is_source: If True, treat the specified module directory as\n        the project root rather than a nested module."
+            "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."
           },
           "generate_config": {
             "name": "generate_config",
             "kind": "function",
             "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\nThe configuration is created by combining a template configuration\nwith a navigation structure derived from the docforge navigation\nspecification.\n\nArgs:\n    docs_dir: Directory containing generated documentation Markdown files.\n    nav_file: Path to the ``docforge.nav.yml`` navigation specification.\n    template: Optional path to a custom MkDocs configuration template.\n        If not provided, a built-in template will be used.\n    out: Destination path where the generated ``mkdocs.yml`` file\n        will be written.\n    site_name: Display name for the generated documentation site.\n\nRaises:\n    click.FileError: If the navigation specification or template\n        file cannot be found."
+            "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_utils.build",
             "signature": "<bound method Alias.signature of Alias('build', 'docforge.cli.mkdocs_utils.build')>",
-            "docstring": "Build the MkDocs documentation site.\n\nThis function loads the MkDocs configuration and runs the MkDocs\nbuild command to generate the final static documentation site.\n\nArgs:\n    mkdocs_yml: Path to the ``mkdocs.yml`` configuration file.\n\nRaises:\n    click.ClickException: If the configuration file does not exist."
+            "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_utils.serve",
             "signature": "<bound method Alias.signature of Alias('serve', 'docforge.cli.mkdocs_utils.serve')>",
-            "docstring": "Start an MkDocs development server with live reload.\n\nThe server watches documentation files and automatically reloads\nthe site when changes are detected.\n\nArgs:\n    mkdocs_yml: Path to the ``mkdocs.yml`` configuration file.\n\nRaises:\n    click.ClickException: If the configuration file does not exist."
+            "docstring": "Serve the documentation site with live-reload using MkDocs.\n\nArgs:\n    mkdocs_yml: Path to the mkdocs.yml configuration file."
           }
         }
       },
@@ -236,21 +229,21 @@
             "kind": "class",
             "path": "docforge.cli.commands.mcp_utils.GriffeLoader",
             "signature": "<bound method Alias.signature of Alias('GriffeLoader', 'docforge.cli.mcp_utils.GriffeLoader')>",
-            "docstring": "Load Python modules using Griffe and convert them into doc-forge models.\n\nThis loader uses the Griffe introspection engine to analyze Python source\ncode and transform the extracted information into ``Project``, ``Module``,\nand ``DocObject`` instances used by doc-forge.",
+            "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_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 assemble them into a Project model.\n\nEach module path is introspected and converted into a ``Module``\ninstance. All modules are then aggregated into a single ``Project``\nobject.\n\nArgs:\n    module_paths: List of dotted module import paths to load.\n    project_name: Optional override for the project name. Defaults\n        to the top-level name of the first module.\n    skip_import_errors: If True, modules that fail to load will be\n        skipped instead of raising an error.\n\nReturns:\n    A populated ``Project`` instance containing the loaded modules.\n\nRaises:\n    ValueError: If no module paths are provided.\n    ImportError: If a module fails to load and\n        ``skip_import_errors`` is False."
+                "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_utils.GriffeLoader.load_module",
                 "signature": "<bound method Alias.signature of Alias('load_module', 'docforge.loaders.griffe_loader.GriffeLoader.load_module')>",
-                "docstring": "Load and convert a single Python module.\n\nThe module is introspected using Griffe and then transformed into\na doc-forge ``Module`` model.\n\nArgs:\n    path: Dotted import path of the module.\n\nReturns:\n    A populated ``Module`` instance."
+                "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."
               }
             }
           },
@@ -259,14 +252,14 @@
             "kind": "function",
             "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 Python modules within a package directory.\n\nThe function scans the filesystem for ``.py`` files inside the specified\npackage and converts them into dotted module import paths.\n\nDiscovery rules:\n\n- Directories containing ``__init__.py`` are treated as packages.\n- Each ``.py`` file is treated as a module.\n- Results are returned as dotted import paths.\n\nArgs:\n    module_name: Top-level package name to discover modules from.\n    project_root: Root directory used to resolve module paths. If not\n        provided, the current working directory is used.\n\nReturns:\n    A sorted list of unique dotted module import paths.\n\nRaises:\n    FileNotFoundError: If the specified package directory does not exist."
+            "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_utils.MCPRenderer",
             "signature": "<bound method Alias.signature of Alias('MCPRenderer', 'docforge.cli.mcp_utils.MCPRenderer')>",
-            "docstring": "Renderer that generates MCP-compatible documentation resources.\n\nThis renderer converts doc-forge project models into structured JSON\nresources suitable for consumption by systems implementing the Model\nContext Protocol (MCP).",
+            "docstring": "Renderer that emits MCP-native JSON resources from docforge models.",
             "members": {
               "name": {
                 "name": "name",
@@ -280,7 +273,7 @@
                 "kind": "function",
                 "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 documentation resources for a project.\n\nThe renderer serializes each module into a JSON resource and produces\nsupporting metadata files such as ``nav.json`` and ``index.json``.\n\nArgs:\n    project: Documentation project model to render.\n    out_dir: Directory where MCP resources will be written."
+                "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."
               }
             }
           },
@@ -289,7 +282,7 @@
             "kind": "class",
             "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-generated documentation bundle.\n\nThe server exposes documentation resources and diagnostic tools through\nMCP endpoints backed by JSON files generated by the MCP renderer.",
+            "docstring": "MCP server for serving a pre-built MCP documentation bundle.",
             "members": {
               "mcp_root": {
                 "name": "mcp_root",
@@ -310,7 +303,7 @@
                 "kind": "function",
                 "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: Transport mechanism used by the MCP server. Supported\n        options include ``stdio``, ``sse``, and ``streamable-http``."
+                "docstring": "Start the MCP server.\n\nArgs:\n    transport: MCP transport (default: streamable-http)"
               }
             }
           },
@@ -319,14 +312,14 @@
             "kind": "function",
             "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 documentation resources from a Python module.\n\nThe function performs project introspection, builds the internal\ndocumentation model, and renders MCP-compatible JSON resources\nto the specified output directory.\n\nArgs:\n    module: Python module import path used as the entry point for\n        documentation generation.\n    project_name: Optional override for the project name used in\n        generated documentation metadata.\n    out_dir: Directory where MCP resources (index.json, nav.json,\n        and module data) will be written."
+            "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_utils.serve",
             "signature": "<bound method Alias.signature of Alias('serve', 'docforge.cli.mcp_utils.serve')>",
-            "docstring": "Start an MCP server for a pre-generated documentation bundle.\n\nThe server exposes documentation resources such as project metadata,\nnavigation structure, and module documentation through MCP endpoints.\n\nArgs:\n    module: Python module import path used to identify the served\n        documentation instance.\n    mcp_root: Path to the directory containing the MCP documentation\n        bundle (index.json, nav.json, and modules/).\n\nRaises:\n    click.ClickException: If the MCP documentation bundle is missing\n        required files or directories."
+            "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/."
           }
         }
       },
@@ -341,22 +334,22 @@
         "name": "build",
         "kind": "function",
         "path": "docforge.cli.commands.build",
-        "signature": "<bound method Function.signature of Function('build', 20, 108)>",
-        "docstring": "Build documentation artifacts.\n\nThis command performs the full documentation build pipeline:\n\n1. Introspects the Python project using Griffe\n2. Generates renderer-specific documentation sources\n3. Optionally builds the final documentation output\n\nDepending on the selected options, the build can target:\n\n- MkDocs static documentation sites\n- MCP structured documentation resources\n\nArgs:\n    mcp: Enable MCP documentation generation.\n    mkdocs: Enable MkDocs documentation generation.\n    module_is_source: Treat the specified module directory as the\n        project root.\n    module: Python module import path to document.\n    project_name: Optional override for the project name.\n    site_name: Display name for the MkDocs site.\n    docs_dir: Directory where Markdown documentation sources\n        will be generated.\n    nav_file: Path to the navigation specification file.\n    template: Optional custom MkDocs configuration template.\n    mkdocs_yml: Output path for the generated MkDocs configuration.\n    out_dir: Output directory for generated MCP resources.\n\nRaises:\n    click.UsageError: If required options are missing or conflicting."
+        "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."
       },
       "serve": {
         "name": "serve",
         "kind": "function",
         "path": "docforge.cli.commands.serve",
-        "signature": "<bound method Function.signature of Function('serve', 111, 152)>",
-        "docstring": "Serve generated documentation locally.\n\nDepending on the selected mode, this command starts either:\n\n- A MkDocs development server for browsing documentation\n- An MCP server exposing structured documentation resources\n\nArgs:\n    mcp: Serve documentation using the MCP server.\n    mkdocs: Serve the MkDocs development site.\n    module: Python module import path to serve via MCP.\n    mkdocs_yml: Path to the MkDocs configuration file.\n    out_dir: Root directory containing MCP documentation resources.\n\nRaises:\n    click.UsageError: If invalid or conflicting options are provided."
+        "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."
       },
       "tree": {
         "name": "tree",
         "kind": "function",
         "path": "docforge.cli.commands.tree",
-        "signature": "<bound method Function.signature of Function('tree', 155, 188)>",
-        "docstring": "Display the documentation object tree for a module.\n\nThis command introspects the specified module and prints a\nhierarchical representation of the discovered documentation\nobjects, including modules, classes, functions, and members.\n\nArgs:\n    module: Python module import path to introspect.\n    project_name: Optional name to display as the project root."
+        "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."
       },
       "Group": {
         "name": "Group",

mcp_docs/modules/docforge.cli.json

@@ -2,14 +2,14 @@
   "module": "docforge.cli",
   "content": {
     "path": "docforge.cli",
-    "docstring": "Command line interface entry point for doc-forge.\n\nThis module exposes the primary CLI entry function used by the\n``doc-forge`` command. The actual command implementation resides in\n``docforge.cli.main``, while this module provides a stable import path\nfor external tools and the package entry point configuration.\n\nThe CLI is responsible for orchestrating documentation workflows such as\ngenerating renderer sources, building documentation sites, exporting\nmachine-readable documentation bundles, and starting development or MCP\nservers.\n\n---\n\nTypical usage\n-------------\n\nThe CLI is normally invoked through the installed command:\n\n    doc-forge <command> [options]\n\nProgrammatic invocation is also possible:\n\n    from docforge.cli import main\n    main()\n\n---",
+    "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": "Command-line entry point for the doc-forge CLI.\n\nThis module exposes the executable entry point that initializes the\nClick command group defined in ``docforge.cli.commands``.",
+        "docstring": "Main entry point for the doc-forge CLI. This module delegates all command\nexecution to docforge.cli.commands.",
         "members": {
           "cli": {
             "name": "cli",
@@ -22,8 +22,8 @@
             "name": "main",
             "kind": "function",
             "path": "docforge.cli.main.main",
-            "signature": "<bound method Function.signature of Function('main', 11, 19)>",
-            "docstring": "Run the doc-forge command-line interface.\n\nThis function initializes and executes the Click CLI application.\nIt is used as the console entry point when invoking ``doc-forge``\nfrom the command line."
+            "signature": "<bound method Function.signature of Function('main', 7, 11)>",
+            "docstring": "CLI Entry point. Boots the click application."
           }
         }
       },
@@ -67,21 +67,21 @@
             "kind": "class",
             "path": "docforge.cli.commands.GriffeLoader",
             "signature": "<bound method Alias.signature of Alias('GriffeLoader', 'docforge.loaders.GriffeLoader')>",
-            "docstring": "Load Python modules using Griffe and convert them into doc-forge models.\n\nThis loader uses the Griffe introspection engine to analyze Python source\ncode and transform the extracted information into ``Project``, ``Module``,\nand ``DocObject`` instances used by doc-forge.",
+            "docstring": "Loads Python modules and extracts documentation using the Griffe introspection engine.",
             "members": {
               "load_project": {
                 "name": "load_project",
                 "kind": "function",
                 "path": "docforge.cli.commands.GriffeLoader.load_project",
                 "signature": "<bound method Alias.signature of Alias('load_project', 'docforge.loaders.griffe_loader.GriffeLoader.load_project')>",
-                "docstring": "Load multiple modules and assemble them into a Project model.\n\nEach module path is introspected and converted into a ``Module``\ninstance. All modules are then aggregated into a single ``Project``\nobject.\n\nArgs:\n    module_paths: List of dotted module import paths to load.\n    project_name: Optional override for the project name. Defaults\n        to the top-level name of the first module.\n    skip_import_errors: If True, modules that fail to load will be\n        skipped instead of raising an error.\n\nReturns:\n    A populated ``Project`` instance containing the loaded modules.\n\nRaises:\n    ValueError: If no module paths are provided.\n    ImportError: If a module fails to load and\n        ``skip_import_errors`` is False."
+                "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.GriffeLoader.load_module",
                 "signature": "<bound method Alias.signature of Alias('load_module', 'docforge.loaders.griffe_loader.GriffeLoader.load_module')>",
-                "docstring": "Load and convert a single Python module.\n\nThe module is introspected using Griffe and then transformed into\na doc-forge ``Module`` model.\n\nArgs:\n    path: Dotted import path of the module.\n\nReturns:\n    A populated ``Module`` instance."
+                "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."
               }
             }
           },
@@ -125,21 +125,21 @@
                 "kind": "class",
                 "path": "docforge.cli.commands.mkdocs_utils.GriffeLoader",
                 "signature": "<bound method Alias.signature of Alias('GriffeLoader', 'docforge.cli.mkdocs_utils.GriffeLoader')>",
-                "docstring": "Load Python modules using Griffe and convert them into doc-forge models.\n\nThis loader uses the Griffe introspection engine to analyze Python source\ncode and transform the extracted information into ``Project``, ``Module``,\nand ``DocObject`` instances used by doc-forge.",
+                "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_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 assemble them into a Project model.\n\nEach module path is introspected and converted into a ``Module``\ninstance. All modules are then aggregated into a single ``Project``\nobject.\n\nArgs:\n    module_paths: List of dotted module import paths to load.\n    project_name: Optional override for the project name. Defaults\n        to the top-level name of the first module.\n    skip_import_errors: If True, modules that fail to load will be\n        skipped instead of raising an error.\n\nReturns:\n    A populated ``Project`` instance containing the loaded modules.\n\nRaises:\n    ValueError: If no module paths are provided.\n    ImportError: If a module fails to load and\n        ``skip_import_errors`` is False."
+                    "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_utils.GriffeLoader.load_module",
                     "signature": "<bound method Alias.signature of Alias('load_module', 'docforge.loaders.griffe_loader.GriffeLoader.load_module')>",
-                    "docstring": "Load and convert a single Python module.\n\nThe module is introspected using Griffe and then transformed into\na doc-forge ``Module`` model.\n\nArgs:\n    path: Dotted import path of the module.\n\nReturns:\n    A populated ``Module`` instance."
+                    "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."
                   }
                 }
               },
@@ -148,14 +148,14 @@
                 "kind": "function",
                 "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 Python modules within a package directory.\n\nThe function scans the filesystem for ``.py`` files inside the specified\npackage and converts them into dotted module import paths.\n\nDiscovery rules:\n\n- Directories containing ``__init__.py`` are treated as packages.\n- Each ``.py`` file is treated as a module.\n- Results are returned as dotted import paths.\n\nArgs:\n    module_name: Top-level package name to discover modules from.\n    project_root: Root directory used to resolve module paths. If not\n        provided, the current working directory is used.\n\nReturns:\n    A sorted list of unique dotted module import paths.\n\nRaises:\n    FileNotFoundError: If the specified package directory does not exist."
+                "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_utils.MkDocsRenderer",
                 "signature": "<bound method Alias.signature of Alias('MkDocsRenderer', 'docforge.cli.mkdocs_utils.MkDocsRenderer')>",
-                "docstring": "Renderer that produces Markdown documentation for MkDocs.\n\nGenerated pages use mkdocstrings directives to reference Python modules,\nallowing MkDocs to render API documentation dynamically.",
+                "docstring": "Renderer that generates Markdown source files formatted for the MkDocs\n'mkdocstrings' plugin.",
                 "members": {
                   "name": {
                     "name": "name",
@@ -169,14 +169,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": "Generate Markdown documentation files for a project.\n\nThis method renders a documentation structure from the provided\nproject model and writes the resulting Markdown files to the\nspecified output directory.\n\nArgs:\n    project: Project model containing modules to document.\n    out_dir: Directory where generated Markdown files will be written.\n    module_is_source: If True, treat the specified module as the\n        documentation root rather than nesting it inside a folder."
-                  },
-                  "generate_readme": {
-                    "name": "generate_readme",
-                    "kind": "function",
-                    "path": "docforge.cli.commands.mkdocs_utils.MkDocsRenderer.generate_readme",
-                    "signature": "<bound method Alias.signature of Alias('generate_readme', 'docforge.renderers.mkdocs_renderer.MkDocsRenderer.generate_readme')>",
-                    "docstring": "Generate a ``README.md`` file from the root module docstring.\n\nBehavior:\n\n- If ``module_is_source`` is True, ``README.md`` is written to the\n  project root directory.\n- If False, README generation is currently not implemented.\n\nArgs:\n    project: Project model containing documentation metadata.\n    docs_dir: Directory containing generated documentation sources.\n    module_is_source: Whether the module is treated as the project\n        source root."
+                    "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."
                   }
                 }
               },
@@ -185,28 +178,28 @@
                 "kind": "function",
                 "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": "Load a navigation specification file.\n\nThis helper function reads a YAML navigation file and constructs a\ncorresponding ``NavSpec`` instance.\n\nArgs:\n    path: Path to the navigation specification file.\n\nReturns:\n    A ``NavSpec`` instance representing the parsed specification.\n\nRaises:\n    FileNotFoundError: If the specification file does not exist.\n    ValueError: If the YAML structure is invalid."
+                "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_utils.resolve_nav",
                 "signature": "<bound method Alias.signature of Alias('resolve_nav', 'docforge.cli.mkdocs_utils.resolve_nav')>",
-                "docstring": "Resolve a navigation specification against the filesystem.\n\nThe function expands glob patterns defined in a ``NavSpec`` and verifies\nthat referenced documentation files exist within the documentation root.\n\nArgs:\n    spec: Navigation specification describing documentation layout.\n    docs_root: Root directory containing documentation Markdown files.\n\nReturns:\n    A ``ResolvedNav`` instance containing validated navigation paths.\n\nRaises:\n    FileNotFoundError: If the documentation root does not exist or a\n        navigation pattern does not match any files."
+                "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_utils.MkDocsNavEmitter",
                 "signature": "<bound method Alias.signature of Alias('MkDocsNavEmitter', 'docforge.cli.mkdocs_utils.MkDocsNavEmitter')>",
-                "docstring": "Emit MkDocs navigation structures from resolved navigation data.\n\nThe emitter transforms a ``ResolvedNav`` object into the YAML-compatible\nlist structure expected by the MkDocs ``nav`` configuration field.",
+                "docstring": "Emitter responsible for transforming a ResolvedNav into an MkDocs-compatible\nnavigation structure.",
                 "members": {
                   "emit": {
                     "name": "emit",
                     "kind": "function",
                     "path": "docforge.cli.commands.mkdocs_utils.MkDocsNavEmitter.emit",
                     "signature": "<bound method Alias.signature of Alias('emit', 'docforge.nav.mkdocs.MkDocsNavEmitter.emit')>",
-                    "docstring": "Generate a navigation structure for ``mkdocs.yml``.\n\nArgs:\n    nav: Resolved navigation data describing documentation groups\n        and their associated Markdown files.\n\nReturns:\n    A list of dictionaries representing the MkDocs navigation layout.\n    Each dictionary maps a navigation label to a page or a list of\n    pages."
+                    "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."
                   }
                 }
               },
@@ -215,28 +208,28 @@
                 "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 MkDocs Markdown sources for a Python module.\n\nThis function introspects the specified module, builds the internal\ndocumentation model, and renders Markdown documentation files for\nuse with MkDocs.\n\nArgs:\n    module: Python module import path used as the entry point for\n        documentation generation.\n    docs_dir: Directory where the generated Markdown files will be written.\n    project_name: Optional override for the project name used in\n        documentation metadata.\n    module_is_source: If True, treat the specified module directory as\n        the project root rather than a nested module."
+                "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."
               },
               "generate_config": {
                 "name": "generate_config",
                 "kind": "function",
                 "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\nThe configuration is created by combining a template configuration\nwith a navigation structure derived from the docforge navigation\nspecification.\n\nArgs:\n    docs_dir: Directory containing generated documentation Markdown files.\n    nav_file: Path to the ``docforge.nav.yml`` navigation specification.\n    template: Optional path to a custom MkDocs configuration template.\n        If not provided, a built-in template will be used.\n    out: Destination path where the generated ``mkdocs.yml`` file\n        will be written.\n    site_name: Display name for the generated documentation site.\n\nRaises:\n    click.FileError: If the navigation specification or template\n        file cannot be found."
+                "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_utils.build",
                 "signature": "<bound method Alias.signature of Alias('build', 'docforge.cli.mkdocs_utils.build')>",
-                "docstring": "Build the MkDocs documentation site.\n\nThis function loads the MkDocs configuration and runs the MkDocs\nbuild command to generate the final static documentation site.\n\nArgs:\n    mkdocs_yml: Path to the ``mkdocs.yml`` configuration file.\n\nRaises:\n    click.ClickException: If the configuration file does not exist."
+                "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_utils.serve",
                 "signature": "<bound method Alias.signature of Alias('serve', 'docforge.cli.mkdocs_utils.serve')>",
-                "docstring": "Start an MkDocs development server with live reload.\n\nThe server watches documentation files and automatically reloads\nthe site when changes are detected.\n\nArgs:\n    mkdocs_yml: Path to the ``mkdocs.yml`` configuration file.\n\nRaises:\n    click.ClickException: If the configuration file does not exist."
+                "docstring": "Serve the documentation site with live-reload using MkDocs.\n\nArgs:\n    mkdocs_yml: Path to the mkdocs.yml configuration file."
               }
             }
           },
@@ -266,21 +259,21 @@
                 "kind": "class",
                 "path": "docforge.cli.commands.mcp_utils.GriffeLoader",
                 "signature": "<bound method Alias.signature of Alias('GriffeLoader', 'docforge.cli.mcp_utils.GriffeLoader')>",
-                "docstring": "Load Python modules using Griffe and convert them into doc-forge models.\n\nThis loader uses the Griffe introspection engine to analyze Python source\ncode and transform the extracted information into ``Project``, ``Module``,\nand ``DocObject`` instances used by doc-forge.",
+                "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_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 assemble them into a Project model.\n\nEach module path is introspected and converted into a ``Module``\ninstance. All modules are then aggregated into a single ``Project``\nobject.\n\nArgs:\n    module_paths: List of dotted module import paths to load.\n    project_name: Optional override for the project name. Defaults\n        to the top-level name of the first module.\n    skip_import_errors: If True, modules that fail to load will be\n        skipped instead of raising an error.\n\nReturns:\n    A populated ``Project`` instance containing the loaded modules.\n\nRaises:\n    ValueError: If no module paths are provided.\n    ImportError: If a module fails to load and\n        ``skip_import_errors`` is False."
+                    "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_utils.GriffeLoader.load_module",
                     "signature": "<bound method Alias.signature of Alias('load_module', 'docforge.loaders.griffe_loader.GriffeLoader.load_module')>",
-                    "docstring": "Load and convert a single Python module.\n\nThe module is introspected using Griffe and then transformed into\na doc-forge ``Module`` model.\n\nArgs:\n    path: Dotted import path of the module.\n\nReturns:\n    A populated ``Module`` instance."
+                    "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."
                   }
                 }
               },
@@ -289,14 +282,14 @@
                 "kind": "function",
                 "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 Python modules within a package directory.\n\nThe function scans the filesystem for ``.py`` files inside the specified\npackage and converts them into dotted module import paths.\n\nDiscovery rules:\n\n- Directories containing ``__init__.py`` are treated as packages.\n- Each ``.py`` file is treated as a module.\n- Results are returned as dotted import paths.\n\nArgs:\n    module_name: Top-level package name to discover modules from.\n    project_root: Root directory used to resolve module paths. If not\n        provided, the current working directory is used.\n\nReturns:\n    A sorted list of unique dotted module import paths.\n\nRaises:\n    FileNotFoundError: If the specified package directory does not exist."
+                "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_utils.MCPRenderer",
                 "signature": "<bound method Alias.signature of Alias('MCPRenderer', 'docforge.cli.mcp_utils.MCPRenderer')>",
-                "docstring": "Renderer that generates MCP-compatible documentation resources.\n\nThis renderer converts doc-forge project models into structured JSON\nresources suitable for consumption by systems implementing the Model\nContext Protocol (MCP).",
+                "docstring": "Renderer that emits MCP-native JSON resources from docforge models.",
                 "members": {
                   "name": {
                     "name": "name",
@@ -310,7 +303,7 @@
                     "kind": "function",
                     "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 documentation resources for a project.\n\nThe renderer serializes each module into a JSON resource and produces\nsupporting metadata files such as ``nav.json`` and ``index.json``.\n\nArgs:\n    project: Documentation project model to render.\n    out_dir: Directory where MCP resources will be written."
+                    "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."
                   }
                 }
               },
@@ -319,7 +312,7 @@
                 "kind": "class",
                 "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-generated documentation bundle.\n\nThe server exposes documentation resources and diagnostic tools through\nMCP endpoints backed by JSON files generated by the MCP renderer.",
+                "docstring": "MCP server for serving a pre-built MCP documentation bundle.",
                 "members": {
                   "mcp_root": {
                     "name": "mcp_root",
@@ -340,7 +333,7 @@
                     "kind": "function",
                     "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: Transport mechanism used by the MCP server. Supported\n        options include ``stdio``, ``sse``, and ``streamable-http``."
+                    "docstring": "Start the MCP server.\n\nArgs:\n    transport: MCP transport (default: streamable-http)"
                   }
                 }
               },
@@ -349,14 +342,14 @@
                 "kind": "function",
                 "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 documentation resources from a Python module.\n\nThe function performs project introspection, builds the internal\ndocumentation model, and renders MCP-compatible JSON resources\nto the specified output directory.\n\nArgs:\n    module: Python module import path used as the entry point for\n        documentation generation.\n    project_name: Optional override for the project name used in\n        generated documentation metadata.\n    out_dir: Directory where MCP resources (index.json, nav.json,\n        and module data) will be written."
+                "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_utils.serve",
                 "signature": "<bound method Alias.signature of Alias('serve', 'docforge.cli.mcp_utils.serve')>",
-                "docstring": "Start an MCP server for a pre-generated documentation bundle.\n\nThe server exposes documentation resources such as project metadata,\nnavigation structure, and module documentation through MCP endpoints.\n\nArgs:\n    module: Python module import path used to identify the served\n        documentation instance.\n    mcp_root: Path to the directory containing the MCP documentation\n        bundle (index.json, nav.json, and modules/).\n\nRaises:\n    click.ClickException: If the MCP documentation bundle is missing\n        required files or directories."
+                "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/."
               }
             }
           },
@@ -371,22 +364,22 @@
             "name": "build",
             "kind": "function",
             "path": "docforge.cli.commands.build",
-            "signature": "<bound method Function.signature of Function('build', 20, 108)>",
-            "docstring": "Build documentation artifacts.\n\nThis command performs the full documentation build pipeline:\n\n1. Introspects the Python project using Griffe\n2. Generates renderer-specific documentation sources\n3. Optionally builds the final documentation output\n\nDepending on the selected options, the build can target:\n\n- MkDocs static documentation sites\n- MCP structured documentation resources\n\nArgs:\n    mcp: Enable MCP documentation generation.\n    mkdocs: Enable MkDocs documentation generation.\n    module_is_source: Treat the specified module directory as the\n        project root.\n    module: Python module import path to document.\n    project_name: Optional override for the project name.\n    site_name: Display name for the MkDocs site.\n    docs_dir: Directory where Markdown documentation sources\n        will be generated.\n    nav_file: Path to the navigation specification file.\n    template: Optional custom MkDocs configuration template.\n    mkdocs_yml: Output path for the generated MkDocs configuration.\n    out_dir: Output directory for generated MCP resources.\n\nRaises:\n    click.UsageError: If required options are missing or conflicting."
+            "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."
           },
           "serve": {
             "name": "serve",
             "kind": "function",
             "path": "docforge.cli.commands.serve",
-            "signature": "<bound method Function.signature of Function('serve', 111, 152)>",
-            "docstring": "Serve generated documentation locally.\n\nDepending on the selected mode, this command starts either:\n\n- A MkDocs development server for browsing documentation\n- An MCP server exposing structured documentation resources\n\nArgs:\n    mcp: Serve documentation using the MCP server.\n    mkdocs: Serve the MkDocs development site.\n    module: Python module import path to serve via MCP.\n    mkdocs_yml: Path to the MkDocs configuration file.\n    out_dir: Root directory containing MCP documentation resources.\n\nRaises:\n    click.UsageError: If invalid or conflicting options are provided."
+            "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."
           },
           "tree": {
             "name": "tree",
             "kind": "function",
             "path": "docforge.cli.commands.tree",
-            "signature": "<bound method Function.signature of Function('tree', 155, 188)>",
-            "docstring": "Display the documentation object tree for a module.\n\nThis command introspects the specified module and prints a\nhierarchical representation of the discovered documentation\nobjects, including modules, classes, functions, and members.\n\nArgs:\n    module: Python module import path to introspect.\n    project_name: Optional name to display as the project root."
+            "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."
           },
           "Group": {
             "name": "Group",
@@ -430,21 +423,21 @@
             "kind": "class",
             "path": "docforge.cli.mcp_utils.GriffeLoader",
             "signature": "<bound method Alias.signature of Alias('GriffeLoader', 'docforge.loaders.GriffeLoader')>",
-            "docstring": "Load Python modules using Griffe and convert them into doc-forge models.\n\nThis loader uses the Griffe introspection engine to analyze Python source\ncode and transform the extracted information into ``Project``, ``Module``,\nand ``DocObject`` instances used by doc-forge.",
+            "docstring": "Loads Python modules and extracts documentation using the Griffe introspection engine.",
             "members": {
               "load_project": {
                 "name": "load_project",
                 "kind": "function",
                 "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 assemble them into a Project model.\n\nEach module path is introspected and converted into a ``Module``\ninstance. All modules are then aggregated into a single ``Project``\nobject.\n\nArgs:\n    module_paths: List of dotted module import paths to load.\n    project_name: Optional override for the project name. Defaults\n        to the top-level name of the first module.\n    skip_import_errors: If True, modules that fail to load will be\n        skipped instead of raising an error.\n\nReturns:\n    A populated ``Project`` instance containing the loaded modules.\n\nRaises:\n    ValueError: If no module paths are provided.\n    ImportError: If a module fails to load and\n        ``skip_import_errors`` is False."
+                "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_utils.GriffeLoader.load_module",
                 "signature": "<bound method Alias.signature of Alias('load_module', 'docforge.loaders.griffe_loader.GriffeLoader.load_module')>",
-                "docstring": "Load and convert a single Python module.\n\nThe module is introspected using Griffe and then transformed into\na doc-forge ``Module`` model.\n\nArgs:\n    path: Dotted import path of the module.\n\nReturns:\n    A populated ``Module`` instance."
+                "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."
               }
             }
           },
@@ -453,14 +446,14 @@
             "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 Python modules within a package directory.\n\nThe function scans the filesystem for ``.py`` files inside the specified\npackage and converts them into dotted module import paths.\n\nDiscovery rules:\n\n- Directories containing ``__init__.py`` are treated as packages.\n- Each ``.py`` file is treated as a module.\n- Results are returned as dotted import paths.\n\nArgs:\n    module_name: Top-level package name to discover modules from.\n    project_root: Root directory used to resolve module paths. If not\n        provided, the current working directory is used.\n\nReturns:\n    A sorted list of unique dotted module import paths.\n\nRaises:\n    FileNotFoundError: If the specified package directory does not exist."
+            "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 generates MCP-compatible documentation resources.\n\nThis renderer converts doc-forge project models into structured JSON\nresources suitable for consumption by systems implementing the Model\nContext Protocol (MCP).",
+            "docstring": "Renderer that emits MCP-native JSON resources from docforge models.",
             "members": {
               "name": {
                 "name": "name",
@@ -474,7 +467,7 @@
                 "kind": "function",
                 "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 documentation resources for a project.\n\nThe renderer serializes each module into a JSON resource and produces\nsupporting metadata files such as ``nav.json`` and ``index.json``.\n\nArgs:\n    project: Documentation project model to render.\n    out_dir: Directory where MCP resources will be written."
+                "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."
               }
             }
           },
@@ -483,7 +476,7 @@
             "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-generated documentation bundle.\n\nThe server exposes documentation resources and diagnostic tools through\nMCP endpoints backed by JSON files generated by the MCP renderer.",
+            "docstring": "MCP server for serving a pre-built MCP documentation bundle.",
             "members": {
               "mcp_root": {
                 "name": "mcp_root",
@@ -504,7 +497,7 @@
                 "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: Transport mechanism used by the MCP server. Supported\n        options include ``stdio``, ``sse``, and ``streamable-http``."
+                "docstring": "Start the MCP server.\n\nArgs:\n    transport: MCP transport (default: streamable-http)"
               }
             }
           },
@@ -512,15 +505,15 @@
             "name": "generate_resources",
             "kind": "function",
             "path": "docforge.cli.mcp_utils.generate_resources",
-            "signature": "<bound method Function.signature of Function('generate_resources', 8, 29)>",
-            "docstring": "Generate MCP documentation resources from a Python module.\n\nThe function performs project introspection, builds the internal\ndocumentation model, and renders MCP-compatible JSON resources\nto the specified output directory.\n\nArgs:\n    module: Python module import path used as the entry point for\n        documentation generation.\n    project_name: Optional override for the project name used in\n        generated documentation metadata.\n    out_dir: Directory where MCP resources (index.json, nav.json,\n        and module data) will be written."
+            "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', 32, 66)>",
-            "docstring": "Start an MCP server for a pre-generated documentation bundle.\n\nThe server exposes documentation resources such as project metadata,\nnavigation structure, and module documentation through MCP endpoints.\n\nArgs:\n    module: Python module import path used to identify the served\n        documentation instance.\n    mcp_root: Path to the directory containing the MCP documentation\n        bundle (index.json, nav.json, and modules/).\n\nRaises:\n    click.ClickException: If the MCP documentation bundle is missing\n        required files or directories."
+            "signature": "<bound method Function.signature of Function('serve', 23, 47)>",
+            "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/."
           }
         }
       },
@@ -564,21 +557,21 @@
             "kind": "class",
             "path": "docforge.cli.mkdocs_utils.GriffeLoader",
             "signature": "<bound method Alias.signature of Alias('GriffeLoader', 'docforge.loaders.GriffeLoader')>",
-            "docstring": "Load Python modules using Griffe and convert them into doc-forge models.\n\nThis loader uses the Griffe introspection engine to analyze Python source\ncode and transform the extracted information into ``Project``, ``Module``,\nand ``DocObject`` instances used by doc-forge.",
+            "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 assemble them into a Project model.\n\nEach module path is introspected and converted into a ``Module``\ninstance. All modules are then aggregated into a single ``Project``\nobject.\n\nArgs:\n    module_paths: List of dotted module import paths to load.\n    project_name: Optional override for the project name. Defaults\n        to the top-level name of the first module.\n    skip_import_errors: If True, modules that fail to load will be\n        skipped instead of raising an error.\n\nReturns:\n    A populated ``Project`` instance containing the loaded modules.\n\nRaises:\n    ValueError: If no module paths are provided.\n    ImportError: If a module fails to load and\n        ``skip_import_errors`` is False."
+                "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 and convert a single Python module.\n\nThe module is introspected using Griffe and then transformed into\na doc-forge ``Module`` model.\n\nArgs:\n    path: Dotted import path of the module.\n\nReturns:\n    A populated ``Module`` instance."
+                "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."
               }
             }
           },
@@ -587,14 +580,14 @@
             "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 Python modules within a package directory.\n\nThe function scans the filesystem for ``.py`` files inside the specified\npackage and converts them into dotted module import paths.\n\nDiscovery rules:\n\n- Directories containing ``__init__.py`` are treated as packages.\n- Each ``.py`` file is treated as a module.\n- Results are returned as dotted import paths.\n\nArgs:\n    module_name: Top-level package name to discover modules from.\n    project_root: Root directory used to resolve module paths. If not\n        provided, the current working directory is used.\n\nReturns:\n    A sorted list of unique dotted module import paths.\n\nRaises:\n    FileNotFoundError: If the specified package directory does not exist."
+            "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 produces Markdown documentation for MkDocs.\n\nGenerated pages use mkdocstrings directives to reference Python modules,\nallowing MkDocs to render API documentation dynamically.",
+            "docstring": "Renderer that generates Markdown source files formatted for the MkDocs\n'mkdocstrings' plugin.",
             "members": {
               "name": {
                 "name": "name",
@@ -608,14 +601,7 @@
                 "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": "Generate Markdown documentation files for a project.\n\nThis method renders a documentation structure from the provided\nproject model and writes the resulting Markdown files to the\nspecified output directory.\n\nArgs:\n    project: Project model containing modules to document.\n    out_dir: Directory where generated Markdown files will be written.\n    module_is_source: If True, treat the specified module as the\n        documentation root rather than nesting it inside a folder."
-              },
-              "generate_readme": {
-                "name": "generate_readme",
-                "kind": "function",
-                "path": "docforge.cli.mkdocs_utils.MkDocsRenderer.generate_readme",
-                "signature": "<bound method Alias.signature of Alias('generate_readme', 'docforge.renderers.mkdocs_renderer.MkDocsRenderer.generate_readme')>",
-                "docstring": "Generate a ``README.md`` file from the root module docstring.\n\nBehavior:\n\n- If ``module_is_source`` is True, ``README.md`` is written to the\n  project root directory.\n- If False, README generation is currently not implemented.\n\nArgs:\n    project: Project model containing documentation metadata.\n    docs_dir: Directory containing generated documentation sources.\n    module_is_source: Whether the module is treated as the project\n        source root."
+                "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."
               }
             }
           },
@@ -624,28 +610,28 @@
             "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": "Load a navigation specification file.\n\nThis helper function reads a YAML navigation file and constructs a\ncorresponding ``NavSpec`` instance.\n\nArgs:\n    path: Path to the navigation specification file.\n\nReturns:\n    A ``NavSpec`` instance representing the parsed specification.\n\nRaises:\n    FileNotFoundError: If the specification file does not exist.\n    ValueError: If the YAML structure is invalid."
+            "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": "Resolve a navigation specification against the filesystem.\n\nThe function expands glob patterns defined in a ``NavSpec`` and verifies\nthat referenced documentation files exist within the documentation root.\n\nArgs:\n    spec: Navigation specification describing documentation layout.\n    docs_root: Root directory containing documentation Markdown files.\n\nReturns:\n    A ``ResolvedNav`` instance containing validated navigation paths.\n\nRaises:\n    FileNotFoundError: If the documentation root does not exist or a\n        navigation pattern does not match any files."
+            "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": "Emit MkDocs navigation structures from resolved navigation data.\n\nThe emitter transforms a ``ResolvedNav`` object into the YAML-compatible\nlist structure expected by the MkDocs ``nav`` configuration field.",
+            "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 navigation structure for ``mkdocs.yml``.\n\nArgs:\n    nav: Resolved navigation data describing documentation groups\n        and their associated Markdown files.\n\nReturns:\n    A list of dictionaries representing the MkDocs navigation layout.\n    Each dictionary maps a navigation label to a page or a list of\n    pages."
+                "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."
               }
             }
           },
@@ -653,29 +639,29 @@
             "name": "generate_sources",
             "kind": "function",
             "path": "docforge.cli.mkdocs_utils.generate_sources",
-            "signature": "<bound method Function.signature of Function('generate_sources', 10, 47)>",
-            "docstring": "Generate MkDocs Markdown sources for a Python module.\n\nThis function introspects the specified module, builds the internal\ndocumentation model, and renders Markdown documentation files for\nuse with MkDocs.\n\nArgs:\n    module: Python module import path used as the entry point for\n        documentation generation.\n    docs_dir: Directory where the generated Markdown files will be written.\n    project_name: Optional override for the project name used in\n        documentation metadata.\n    module_is_source: If True, treat the specified module directory as\n        the project root rather than a nested module."
+            "signature": "<bound method Function.signature of Function('generate_sources', 9, 23)>",
+            "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."
           },
           "generate_config": {
             "name": "generate_config",
             "kind": "function",
             "path": "docforge.cli.mkdocs_utils.generate_config",
-            "signature": "<bound method Function.signature of Function('generate_config', 50, 100)>",
-            "docstring": "Generate an ``mkdocs.yml`` configuration file.\n\nThe configuration is created by combining a template configuration\nwith a navigation structure derived from the docforge navigation\nspecification.\n\nArgs:\n    docs_dir: Directory containing generated documentation Markdown files.\n    nav_file: Path to the ``docforge.nav.yml`` navigation specification.\n    template: Optional path to a custom MkDocs configuration template.\n        If not provided, a built-in template will be used.\n    out: Destination path where the generated ``mkdocs.yml`` file\n        will be written.\n    site_name: Display name for the generated documentation site.\n\nRaises:\n    click.FileError: If the navigation specification or template\n        file cannot be found."
+            "signature": "<bound method Function.signature of Function('generate_config', 25, 59)>",
+            "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', 103, 122)>",
-            "docstring": "Build the MkDocs documentation site.\n\nThis function loads the MkDocs configuration and runs the MkDocs\nbuild command to generate the final static documentation site.\n\nArgs:\n    mkdocs_yml: Path to the ``mkdocs.yml`` configuration file.\n\nRaises:\n    click.ClickException: If the configuration file does not exist."
+            "signature": "<bound method Function.signature of Function('build', 61, 74)>",
+            "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', 125, 142)>",
-            "docstring": "Start an MkDocs development server with live reload.\n\nThe server watches documentation files and automatically reloads\nthe site when changes are detected.\n\nArgs:\n    mkdocs_yml: Path to the ``mkdocs.yml`` configuration file.\n\nRaises:\n    click.ClickException: If the configuration file does not exist."
+            "signature": "<bound method Function.signature of Function('serve', 76, 87)>",
+            "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,7 +2,7 @@
   "module": "docforge.cli.main",
   "content": {
     "path": "docforge.cli.main",
-    "docstring": "Command-line entry point for the doc-forge CLI.\n\nThis module exposes the executable entry point that initializes the\nClick command group defined in ``docforge.cli.commands``.",
+    "docstring": "Main entry point for the doc-forge CLI. This module delegates all command\nexecution to docforge.cli.commands.",
     "objects": {
       "cli": {
         "name": "cli",
@@ -15,8 +15,8 @@
         "name": "main",
         "kind": "function",
         "path": "docforge.cli.main.main",
-        "signature": "<bound method Function.signature of Function('main', 11, 19)>",
-        "docstring": "Run the doc-forge command-line interface.\n\nThis function initializes and executes the Click CLI application.\nIt is used as the console entry point when invoking ``doc-forge``\nfrom the command line."
+        "signature": "<bound method Function.signature of Function('main', 7, 11)>",
+        "docstring": "CLI Entry point. Boots the click application."
       }
     }
   }

mcp_docs/modules/docforge.cli.mcp_utils.json

@@ -23,21 +23,21 @@
         "kind": "class",
         "path": "docforge.cli.mcp_utils.GriffeLoader",
         "signature": "<bound method Alias.signature of Alias('GriffeLoader', 'docforge.loaders.GriffeLoader')>",
-        "docstring": "Load Python modules using Griffe and convert them into doc-forge models.\n\nThis loader uses the Griffe introspection engine to analyze Python source\ncode and transform the extracted information into ``Project``, ``Module``,\nand ``DocObject`` instances used by doc-forge.",
+        "docstring": "Loads Python modules and extracts documentation using the Griffe introspection engine.",
         "members": {
           "load_project": {
             "name": "load_project",
             "kind": "function",
             "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 assemble them into a Project model.\n\nEach module path is introspected and converted into a ``Module``\ninstance. All modules are then aggregated into a single ``Project``\nobject.\n\nArgs:\n    module_paths: List of dotted module import paths to load.\n    project_name: Optional override for the project name. Defaults\n        to the top-level name of the first module.\n    skip_import_errors: If True, modules that fail to load will be\n        skipped instead of raising an error.\n\nReturns:\n    A populated ``Project`` instance containing the loaded modules.\n\nRaises:\n    ValueError: If no module paths are provided.\n    ImportError: If a module fails to load and\n        ``skip_import_errors`` is False."
+            "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_utils.GriffeLoader.load_module",
             "signature": "<bound method Alias.signature of Alias('load_module', 'docforge.loaders.griffe_loader.GriffeLoader.load_module')>",
-            "docstring": "Load and convert a single Python module.\n\nThe module is introspected using Griffe and then transformed into\na doc-forge ``Module`` model.\n\nArgs:\n    path: Dotted import path of the module.\n\nReturns:\n    A populated ``Module`` instance."
+            "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."
           }
         }
       },
@@ -46,14 +46,14 @@
         "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 Python modules within a package directory.\n\nThe function scans the filesystem for ``.py`` files inside the specified\npackage and converts them into dotted module import paths.\n\nDiscovery rules:\n\n- Directories containing ``__init__.py`` are treated as packages.\n- Each ``.py`` file is treated as a module.\n- Results are returned as dotted import paths.\n\nArgs:\n    module_name: Top-level package name to discover modules from.\n    project_root: Root directory used to resolve module paths. If not\n        provided, the current working directory is used.\n\nReturns:\n    A sorted list of unique dotted module import paths.\n\nRaises:\n    FileNotFoundError: If the specified package directory does not exist."
+        "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 generates MCP-compatible documentation resources.\n\nThis renderer converts doc-forge project models into structured JSON\nresources suitable for consumption by systems implementing the Model\nContext Protocol (MCP).",
+        "docstring": "Renderer that emits MCP-native JSON resources from docforge models.",
         "members": {
           "name": {
             "name": "name",
@@ -67,7 +67,7 @@
             "kind": "function",
             "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 documentation resources for a project.\n\nThe renderer serializes each module into a JSON resource and produces\nsupporting metadata files such as ``nav.json`` and ``index.json``.\n\nArgs:\n    project: Documentation project model to render.\n    out_dir: Directory where MCP resources will be written."
+            "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."
           }
         }
       },
@@ -76,7 +76,7 @@
         "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-generated documentation bundle.\n\nThe server exposes documentation resources and diagnostic tools through\nMCP endpoints backed by JSON files generated by the MCP renderer.",
+        "docstring": "MCP server for serving a pre-built MCP documentation bundle.",
         "members": {
           "mcp_root": {
             "name": "mcp_root",
@@ -97,7 +97,7 @@
             "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: Transport mechanism used by the MCP server. Supported\n        options include ``stdio``, ``sse``, and ``streamable-http``."
+            "docstring": "Start the MCP server.\n\nArgs:\n    transport: MCP transport (default: streamable-http)"
           }
         }
       },
@@ -105,15 +105,15 @@
         "name": "generate_resources",
         "kind": "function",
         "path": "docforge.cli.mcp_utils.generate_resources",
-        "signature": "<bound method Function.signature of Function('generate_resources', 8, 29)>",
-        "docstring": "Generate MCP documentation resources from a Python module.\n\nThe function performs project introspection, builds the internal\ndocumentation model, and renders MCP-compatible JSON resources\nto the specified output directory.\n\nArgs:\n    module: Python module import path used as the entry point for\n        documentation generation.\n    project_name: Optional override for the project name used in\n        generated documentation metadata.\n    out_dir: Directory where MCP resources (index.json, nav.json,\n        and module data) will be written."
+        "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', 32, 66)>",
-        "docstring": "Start an MCP server for a pre-generated documentation bundle.\n\nThe server exposes documentation resources such as project metadata,\nnavigation structure, and module documentation through MCP endpoints.\n\nArgs:\n    module: Python module import path used to identify the served\n        documentation instance.\n    mcp_root: Path to the directory containing the MCP documentation\n        bundle (index.json, nav.json, and modules/).\n\nRaises:\n    click.ClickException: If the MCP documentation bundle is missing\n        required files or directories."
+        "signature": "<bound method Function.signature of Function('serve', 23, 47)>",
+        "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/."
       }
     }
   }

mcp_docs/modules/docforge.cli.mkdocs_utils.json

@@ -37,21 +37,21 @@
         "kind": "class",
         "path": "docforge.cli.mkdocs_utils.GriffeLoader",
         "signature": "<bound method Alias.signature of Alias('GriffeLoader', 'docforge.loaders.GriffeLoader')>",
-        "docstring": "Load Python modules using Griffe and convert them into doc-forge models.\n\nThis loader uses the Griffe introspection engine to analyze Python source\ncode and transform the extracted information into ``Project``, ``Module``,\nand ``DocObject`` instances used by doc-forge.",
+        "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 assemble them into a Project model.\n\nEach module path is introspected and converted into a ``Module``\ninstance. All modules are then aggregated into a single ``Project``\nobject.\n\nArgs:\n    module_paths: List of dotted module import paths to load.\n    project_name: Optional override for the project name. Defaults\n        to the top-level name of the first module.\n    skip_import_errors: If True, modules that fail to load will be\n        skipped instead of raising an error.\n\nReturns:\n    A populated ``Project`` instance containing the loaded modules.\n\nRaises:\n    ValueError: If no module paths are provided.\n    ImportError: If a module fails to load and\n        ``skip_import_errors`` is False."
+            "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 and convert a single Python module.\n\nThe module is introspected using Griffe and then transformed into\na doc-forge ``Module`` model.\n\nArgs:\n    path: Dotted import path of the module.\n\nReturns:\n    A populated ``Module`` instance."
+            "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."
           }
         }
       },
@@ -60,14 +60,14 @@
         "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 Python modules within a package directory.\n\nThe function scans the filesystem for ``.py`` files inside the specified\npackage and converts them into dotted module import paths.\n\nDiscovery rules:\n\n- Directories containing ``__init__.py`` are treated as packages.\n- Each ``.py`` file is treated as a module.\n- Results are returned as dotted import paths.\n\nArgs:\n    module_name: Top-level package name to discover modules from.\n    project_root: Root directory used to resolve module paths. If not\n        provided, the current working directory is used.\n\nReturns:\n    A sorted list of unique dotted module import paths.\n\nRaises:\n    FileNotFoundError: If the specified package directory does not exist."
+        "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 produces Markdown documentation for MkDocs.\n\nGenerated pages use mkdocstrings directives to reference Python modules,\nallowing MkDocs to render API documentation dynamically.",
+        "docstring": "Renderer that generates Markdown source files formatted for the MkDocs\n'mkdocstrings' plugin.",
         "members": {
           "name": {
             "name": "name",
@@ -81,14 +81,7 @@
             "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": "Generate Markdown documentation files for a project.\n\nThis method renders a documentation structure from the provided\nproject model and writes the resulting Markdown files to the\nspecified output directory.\n\nArgs:\n    project: Project model containing modules to document.\n    out_dir: Directory where generated Markdown files will be written.\n    module_is_source: If True, treat the specified module as the\n        documentation root rather than nesting it inside a folder."
-          },
-          "generate_readme": {
-            "name": "generate_readme",
-            "kind": "function",
-            "path": "docforge.cli.mkdocs_utils.MkDocsRenderer.generate_readme",
-            "signature": "<bound method Alias.signature of Alias('generate_readme', 'docforge.renderers.mkdocs_renderer.MkDocsRenderer.generate_readme')>",
-            "docstring": "Generate a ``README.md`` file from the root module docstring.\n\nBehavior:\n\n- If ``module_is_source`` is True, ``README.md`` is written to the\n  project root directory.\n- If False, README generation is currently not implemented.\n\nArgs:\n    project: Project model containing documentation metadata.\n    docs_dir: Directory containing generated documentation sources.\n    module_is_source: Whether the module is treated as the project\n        source root."
+            "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."
           }
         }
       },
@@ -97,28 +90,28 @@
         "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": "Load a navigation specification file.\n\nThis helper function reads a YAML navigation file and constructs a\ncorresponding ``NavSpec`` instance.\n\nArgs:\n    path: Path to the navigation specification file.\n\nReturns:\n    A ``NavSpec`` instance representing the parsed specification.\n\nRaises:\n    FileNotFoundError: If the specification file does not exist.\n    ValueError: If the YAML structure is invalid."
+        "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": "Resolve a navigation specification against the filesystem.\n\nThe function expands glob patterns defined in a ``NavSpec`` and verifies\nthat referenced documentation files exist within the documentation root.\n\nArgs:\n    spec: Navigation specification describing documentation layout.\n    docs_root: Root directory containing documentation Markdown files.\n\nReturns:\n    A ``ResolvedNav`` instance containing validated navigation paths.\n\nRaises:\n    FileNotFoundError: If the documentation root does not exist or a\n        navigation pattern does not match any files."
+        "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": "Emit MkDocs navigation structures from resolved navigation data.\n\nThe emitter transforms a ``ResolvedNav`` object into the YAML-compatible\nlist structure expected by the MkDocs ``nav`` configuration field.",
+        "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 navigation structure for ``mkdocs.yml``.\n\nArgs:\n    nav: Resolved navigation data describing documentation groups\n        and their associated Markdown files.\n\nReturns:\n    A list of dictionaries representing the MkDocs navigation layout.\n    Each dictionary maps a navigation label to a page or a list of\n    pages."
+            "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."
           }
         }
       },
@@ -126,29 +119,29 @@
         "name": "generate_sources",
         "kind": "function",
         "path": "docforge.cli.mkdocs_utils.generate_sources",
-        "signature": "<bound method Function.signature of Function('generate_sources', 10, 47)>",
-        "docstring": "Generate MkDocs Markdown sources for a Python module.\n\nThis function introspects the specified module, builds the internal\ndocumentation model, and renders Markdown documentation files for\nuse with MkDocs.\n\nArgs:\n    module: Python module import path used as the entry point for\n        documentation generation.\n    docs_dir: Directory where the generated Markdown files will be written.\n    project_name: Optional override for the project name used in\n        documentation metadata.\n    module_is_source: If True, treat the specified module directory as\n        the project root rather than a nested module."
+        "signature": "<bound method Function.signature of Function('generate_sources', 9, 23)>",
+        "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."
       },
       "generate_config": {
         "name": "generate_config",
         "kind": "function",
         "path": "docforge.cli.mkdocs_utils.generate_config",
-        "signature": "<bound method Function.signature of Function('generate_config', 50, 100)>",
-        "docstring": "Generate an ``mkdocs.yml`` configuration file.\n\nThe configuration is created by combining a template configuration\nwith a navigation structure derived from the docforge navigation\nspecification.\n\nArgs:\n    docs_dir: Directory containing generated documentation Markdown files.\n    nav_file: Path to the ``docforge.nav.yml`` navigation specification.\n    template: Optional path to a custom MkDocs configuration template.\n        If not provided, a built-in template will be used.\n    out: Destination path where the generated ``mkdocs.yml`` file\n        will be written.\n    site_name: Display name for the generated documentation site.\n\nRaises:\n    click.FileError: If the navigation specification or template\n        file cannot be found."
+        "signature": "<bound method Function.signature of Function('generate_config', 25, 59)>",
+        "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', 103, 122)>",
-        "docstring": "Build the MkDocs documentation site.\n\nThis function loads the MkDocs configuration and runs the MkDocs\nbuild command to generate the final static documentation site.\n\nArgs:\n    mkdocs_yml: Path to the ``mkdocs.yml`` configuration file.\n\nRaises:\n    click.ClickException: If the configuration file does not exist."
+        "signature": "<bound method Function.signature of Function('build', 61, 74)>",
+        "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', 125, 142)>",
-        "docstring": "Start an MkDocs development server with live reload.\n\nThe server watches documentation files and automatically reloads\nthe site when changes are detected.\n\nArgs:\n    mkdocs_yml: Path to the ``mkdocs.yml`` configuration file.\n\nRaises:\n    click.ClickException: If the configuration file does not exist."
+        "signature": "<bound method Function.signature of Function('serve', 76, 87)>",
+        "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.loaders.griffe_loader.json

@@ -2,7 +2,7 @@
   "module": "docforge.loaders.griffe_loader",
   "content": {
     "path": "docforge.loaders.griffe_loader",
-    "docstring": "Utilities for loading and introspecting Python modules using Griffe.\n\nThis module provides the ``GriffeLoader`` class and helper utilities used to\ndiscover Python modules, introspect their structure, and convert the results\ninto doc-forge documentation models.",
+    "docstring": "This module provides the GriffeLoader, which uses the 'griffe' library to\nintrospect Python source code and populate the doc-forge Project models.",
     "objects": {
       "logging": {
         "name": "logging",
@@ -65,7 +65,7 @@
         "kind": "class",
         "path": "docforge.loaders.griffe_loader.Module",
         "signature": "<bound method Alias.signature of Alias('Module', 'docforge.models.Module')>",
-        "docstring": "Representation of a documented Python module or package.\n\nA ``Module`` stores metadata about the module itself and maintains a\ncollection of top-level documentation objects discovered during\nintrospection.\n\nAttributes:\n    path: Dotted import path of the module.\n    docstring: Module-level documentation string, if present.\n    members: Mapping of object names to their corresponding\n        ``DocObject`` representations.",
+        "docstring": "Represents a documented Python module or package.\n\nAttributes:\n    path: Dotted import path of the module.\n    docstring: Module-level docstring content.\n    members: Dictionary mapping object names to their DocObject representations.",
         "members": {
           "path": {
             "name": "path",
@@ -93,21 +93,21 @@
             "kind": "function",
             "path": "docforge.loaders.griffe_loader.Module.add_object",
             "signature": "<bound method Alias.signature of Alias('add_object', 'docforge.models.module.Module.add_object')>",
-            "docstring": "Add a documented object to the module.\n\nArgs:\n    obj: Documentation object to register as a top-level\n        member of the module."
+            "docstring": "Add a documented object to the module.\n\nArgs:\n    obj: The object to add."
           },
           "get_object": {
             "name": "get_object",
             "kind": "function",
             "path": "docforge.loaders.griffe_loader.Module.get_object",
             "signature": "<bound method Alias.signature of Alias('get_object', 'docforge.models.module.Module.get_object')>",
-            "docstring": "Retrieve a documented object by name.\n\nArgs:\n    name: Name of the object to retrieve.\n\nReturns:\n    The corresponding ``DocObject`` instance.\n\nRaises:\n    KeyError: If no object with the given name exists."
+            "docstring": "Retrieve a member object by name.\n\nArgs:\n    name: The name of the object.\n\nReturns:\n    The requested DocObject."
           },
           "get_all_objects": {
             "name": "get_all_objects",
             "kind": "function",
             "path": "docforge.loaders.griffe_loader.Module.get_all_objects",
             "signature": "<bound method Alias.signature of Alias('get_all_objects', 'docforge.models.module.Module.get_all_objects')>",
-            "docstring": "Return all top-level documentation objects in the module.\n\nReturns:\n    An iterable of ``DocObject`` instances representing the\n    module's public members."
+            "docstring": "Get all top-level objects in the module.\n\nReturns:\n    An iterable of DocObject instances."
           }
         }
       },
@@ -116,7 +116,7 @@
         "kind": "class",
         "path": "docforge.loaders.griffe_loader.Project",
         "signature": "<bound method Alias.signature of Alias('Project', 'docforge.models.Project')>",
-        "docstring": "Representation of a documentation project.\n\nA ``Project`` serves as the root container for all modules discovered during\nintrospection. Each module is stored by its dotted import path.\n\nAttributes:\n    name: Name of the project.\n    modules: Mapping of module paths to ``Module`` instances.",
+        "docstring": "Represents a documentation project, serving as a container for modules.\n\nAttributes:\n    name: Name of the project.\n    modules: Dictionary mapping module paths to Module instances.",
         "members": {
           "name": {
             "name": "name",
@@ -137,28 +137,28 @@
             "kind": "function",
             "path": "docforge.loaders.griffe_loader.Project.add_module",
             "signature": "<bound method Alias.signature of Alias('add_module', 'docforge.models.project.Project.add_module')>",
-            "docstring": "Register a module in the project.\n\nArgs:\n    module: Module instance to add to the project."
+            "docstring": "Add a module to the project.\n\nArgs:\n    module: The module to add."
           },
           "get_module": {
             "name": "get_module",
             "kind": "function",
             "path": "docforge.loaders.griffe_loader.Project.get_module",
             "signature": "<bound method Alias.signature of Alias('get_module', 'docforge.models.project.Project.get_module')>",
-            "docstring": "Retrieve a module by its dotted path.\n\nArgs:\n    path: Fully qualified dotted module path (for example ``pkg.module``).\n\nReturns:\n    The corresponding ``Module`` instance.\n\nRaises:\n    KeyError: If the module does not exist in the project."
+            "docstring": "Retrieve a module by its dotted path.\n\nArgs:\n    path: The dotted path of the module (e.g., 'pkg.mod').\n\nReturns:\n    The requested Module."
           },
           "get_all_modules": {
             "name": "get_all_modules",
             "kind": "function",
             "path": "docforge.loaders.griffe_loader.Project.get_all_modules",
             "signature": "<bound method Alias.signature of Alias('get_all_modules', 'docforge.models.project.Project.get_all_modules')>",
-            "docstring": "Return all modules contained in the project.\n\nReturns:\n    An iterable of ``Module`` instances."
+            "docstring": "Get all modules in the project.\n\nReturns:\n    An iterable of Module objects."
           },
           "get_module_list": {
             "name": "get_module_list",
             "kind": "function",
             "path": "docforge.loaders.griffe_loader.Project.get_module_list",
             "signature": "<bound method Alias.signature of Alias('get_module_list', 'docforge.models.project.Project.get_module_list')>",
-            "docstring": "Return the list of module import paths.\n\nReturns:\n    A list containing the dotted paths of all modules in the project."
+            "docstring": "Get the list of all module dotted paths.\n\nReturns:\n    A list of module paths."
           }
         }
       },
@@ -167,7 +167,7 @@
         "kind": "class",
         "path": "docforge.loaders.griffe_loader.DocObject",
         "signature": "<bound method Alias.signature of Alias('DocObject', 'docforge.models.DocObject')>",
-        "docstring": "Representation of a documented Python object.\n\nA ``DocObject`` models a single Python entity discovered during\nintrospection. Objects may contain nested members, allowing the structure\nof modules, classes, and other containers to be represented recursively.\n\nAttributes:\n    name: Local name of the object.\n    kind: Type of object (for example ``class``, ``function``,\n        ``method``, or ``attribute``).\n    path: Fully qualified dotted path to the object.\n    signature: Callable signature if the object represents a callable.\n    docstring: Raw docstring text extracted from the source code.\n    members: Mapping of member names to child ``DocObject`` instances.",
+        "docstring": "Represents a documented Python object (class, function, method, etc.).\n\nAttributes:\n    name: Local name of the object.\n    kind: Type of object (e.g., 'class', 'function', 'attribute').\n    path: Full dotted import path to the object.\n    signature: Callable signature, if applicable.\n    docstring: Raw docstring content extracted from the source.\n    members: Dictionary mapping member names to their DocObject representations.",
         "members": {
           "name": {
             "name": "name",
@@ -216,21 +216,21 @@
             "kind": "function",
             "path": "docforge.loaders.griffe_loader.DocObject.add_member",
             "signature": "<bound method Alias.signature of Alias('add_member', 'docforge.models.object.DocObject.add_member')>",
-            "docstring": "Add a child documentation object.\n\nThis is typically used when attaching methods to classes or\nnested objects to their parent containers.\n\nArgs:\n    obj: Documentation object to add as a member."
+            "docstring": "Add a child member to this object (e.g., a method to a class).\n\nArgs:\n    obj: The child DocObject to add."
           },
           "get_member": {
             "name": "get_member",
             "kind": "function",
             "path": "docforge.loaders.griffe_loader.DocObject.get_member",
             "signature": "<bound method Alias.signature of Alias('get_member', 'docforge.models.object.DocObject.get_member')>",
-            "docstring": "Retrieve a member object by name.\n\nArgs:\n    name: Name of the member to retrieve.\n\nReturns:\n    The corresponding ``DocObject`` instance.\n\nRaises:\n    KeyError: If the member does not exist."
+            "docstring": "Retrieve a child member by name.\n\nArgs:\n    name: The name of the member.\n\nReturns:\n    The requested DocObject."
           },
           "get_all_members": {
             "name": "get_all_members",
             "kind": "function",
             "path": "docforge.loaders.griffe_loader.DocObject.get_all_members",
             "signature": "<bound method Alias.signature of Alias('get_all_members', 'docforge.models.object.DocObject.get_all_members')>",
-            "docstring": "Return all child members of the object.\n\nReturns:\n    An iterable of ``DocObject`` instances representing nested members."
+            "docstring": "Get all members of this object.\n\nReturns:\n    An iterable of child DocObject instances."
           }
         }
       },
@@ -245,29 +245,29 @@
         "name": "discover_module_paths",
         "kind": "function",
         "path": "docforge.loaders.griffe_loader.discover_module_paths",
-        "signature": "<bound method Function.signature of Function('discover_module_paths', 26, 73)>",
-        "docstring": "Discover Python modules within a package directory.\n\nThe function scans the filesystem for ``.py`` files inside the specified\npackage and converts them into dotted module import paths.\n\nDiscovery rules:\n\n- Directories containing ``__init__.py`` are treated as packages.\n- Each ``.py`` file is treated as a module.\n- Results are returned as dotted import paths.\n\nArgs:\n    module_name: Top-level package name to discover modules from.\n    project_root: Root directory used to resolve module paths. If not\n        provided, the current working directory is used.\n\nReturns:\n    A sorted list of unique dotted module import paths.\n\nRaises:\n    FileNotFoundError: If the specified package directory does not exist."
+        "signature": "<bound method Function.signature of Function('discover_module_paths', 23, 62)>",
+        "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."
       },
       "GriffeLoader": {
         "name": "GriffeLoader",
         "kind": "class",
         "path": "docforge.loaders.griffe_loader.GriffeLoader",
-        "signature": "<bound method Class.signature of Class('GriffeLoader', 76, 264)>",
-        "docstring": "Load Python modules using Griffe and convert them into doc-forge models.\n\nThis loader uses the Griffe introspection engine to analyze Python source\ncode and transform the extracted information into ``Project``, ``Module``,\nand ``DocObject`` instances used by doc-forge.",
+        "signature": "<bound method Class.signature of Class('GriffeLoader', 65, 224)>",
+        "docstring": "Loads Python modules and extracts documentation using the Griffe introspection engine.",
         "members": {
           "load_project": {
             "name": "load_project",
             "kind": "function",
             "path": "docforge.loaders.griffe_loader.GriffeLoader.load_project",
-            "signature": "<bound method Function.signature of Function('load_project', 97, 144)>",
-            "docstring": "Load multiple modules and assemble them into a Project model.\n\nEach module path is introspected and converted into a ``Module``\ninstance. All modules are then aggregated into a single ``Project``\nobject.\n\nArgs:\n    module_paths: List of dotted module import paths to load.\n    project_name: Optional override for the project name. Defaults\n        to the top-level name of the first module.\n    skip_import_errors: If True, modules that fail to load will be\n        skipped instead of raising an error.\n\nReturns:\n    A populated ``Project`` instance containing the loaded modules.\n\nRaises:\n    ValueError: If no module paths are provided.\n    ImportError: If a module fails to load and\n        ``skip_import_errors`` is False."
+            "signature": "<bound method Function.signature of Function('load_project', 79, 115)>",
+            "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.loaders.griffe_loader.GriffeLoader.load_module",
-            "signature": "<bound method Function.signature of Function('load_module', 146, 162)>",
-            "docstring": "Load and convert a single Python module.\n\nThe module is introspected using Griffe and then transformed into\na doc-forge ``Module`` model.\n\nArgs:\n    path: Dotted import path of the module.\n\nReturns:\n    A populated ``Module`` instance."
+            "signature": "<bound method Function.signature of Function('load_module', 117, 130)>",
+            "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."
           }
         }
       }

mcp_docs/modules/docforge.loaders.json

@@ -2,28 +2,28 @@
   "module": "docforge.loaders",
   "content": {
     "path": "docforge.loaders",
-    "docstring": "Loader layer for doc-forge.\n\nThe ``docforge.loaders`` package is responsible for discovering Python modules\nand extracting documentation data using static analysis.\n\n---\n\nOverview\n--------\n\nThis layer converts Python source code into an intermediate documentation\nmodel used by doc-forge. It performs module discovery, introspection, and\ninitial filtering before the data is passed to the core documentation models.\n\nCore capabilities include:\n\n- **Module discovery** – Locate Python modules and packages within a project.\n- **Static introspection** – Parse docstrings, signatures, and object\n  hierarchies using the ``griffe`` library without executing the code.\n- **Public API filtering** – Exclude private members (names prefixed with\n  ``_``) to produce clean public documentation structures.\n\n---",
+    "docstring": "# Loader Layer\n\nThe `docforge.loaders` package is responsible for discovering Python source files\nand extracting their documentation using static analysis.\n\n## Core Features\n\n- **Discovery**: Automatically find all modules and packages in a project\n  directory.\n- **Introspection**: Uses `griffe` to parse docstrings, signatures, and\n  hierarchical relationships without executing the code.\n- **Filtering**: Automatically excludes private members (prefixed with `_`) to\n  ensure clean public documentation.",
     "objects": {
       "GriffeLoader": {
         "name": "GriffeLoader",
         "kind": "class",
         "path": "docforge.loaders.GriffeLoader",
         "signature": "<bound method Alias.signature of Alias('GriffeLoader', 'docforge.loaders.griffe_loader.GriffeLoader')>",
-        "docstring": "Load Python modules using Griffe and convert them into doc-forge models.\n\nThis loader uses the Griffe introspection engine to analyze Python source\ncode and transform the extracted information into ``Project``, ``Module``,\nand ``DocObject`` instances used by doc-forge.",
+        "docstring": "Loads Python modules and extracts documentation using the Griffe introspection engine.",
         "members": {
           "load_project": {
             "name": "load_project",
             "kind": "function",
             "path": "docforge.loaders.GriffeLoader.load_project",
             "signature": "<bound method Alias.signature of Alias('load_project', 'docforge.loaders.griffe_loader.GriffeLoader.load_project')>",
-            "docstring": "Load multiple modules and assemble them into a Project model.\n\nEach module path is introspected and converted into a ``Module``\ninstance. All modules are then aggregated into a single ``Project``\nobject.\n\nArgs:\n    module_paths: List of dotted module import paths to load.\n    project_name: Optional override for the project name. Defaults\n        to the top-level name of the first module.\n    skip_import_errors: If True, modules that fail to load will be\n        skipped instead of raising an error.\n\nReturns:\n    A populated ``Project`` instance containing the loaded modules.\n\nRaises:\n    ValueError: If no module paths are provided.\n    ImportError: If a module fails to load and\n        ``skip_import_errors`` is False."
+            "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.loaders.GriffeLoader.load_module",
             "signature": "<bound method Alias.signature of Alias('load_module', 'docforge.loaders.griffe_loader.GriffeLoader.load_module')>",
-            "docstring": "Load and convert a single Python module.\n\nThe module is introspected using Griffe and then transformed into\na doc-forge ``Module`` model.\n\nArgs:\n    path: Dotted import path of the module.\n\nReturns:\n    A populated ``Module`` instance."
+            "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."
           }
         }
       },
@@ -32,14 +32,14 @@
         "kind": "function",
         "path": "docforge.loaders.discover_module_paths",
         "signature": "<bound method Alias.signature of Alias('discover_module_paths', 'docforge.loaders.griffe_loader.discover_module_paths')>",
-        "docstring": "Discover Python modules within a package directory.\n\nThe function scans the filesystem for ``.py`` files inside the specified\npackage and converts them into dotted module import paths.\n\nDiscovery rules:\n\n- Directories containing ``__init__.py`` are treated as packages.\n- Each ``.py`` file is treated as a module.\n- Results are returned as dotted import paths.\n\nArgs:\n    module_name: Top-level package name to discover modules from.\n    project_root: Root directory used to resolve module paths. If not\n        provided, the current working directory is used.\n\nReturns:\n    A sorted list of unique dotted module import paths.\n\nRaises:\n    FileNotFoundError: If the specified package directory does not exist."
+        "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."
       },
       "griffe_loader": {
         "name": "griffe_loader",
         "kind": "module",
         "path": "docforge.loaders.griffe_loader",
         "signature": null,
-        "docstring": "Utilities for loading and introspecting Python modules using Griffe.\n\nThis module provides the ``GriffeLoader`` class and helper utilities used to\ndiscover Python modules, introspect their structure, and convert the results\ninto doc-forge documentation models.",
+        "docstring": "This module provides the GriffeLoader, which uses the 'griffe' library to\nintrospect Python source code and populate the doc-forge Project models.",
         "members": {
           "logging": {
             "name": "logging",
@@ -102,7 +102,7 @@
             "kind": "class",
             "path": "docforge.loaders.griffe_loader.Module",
             "signature": "<bound method Alias.signature of Alias('Module', 'docforge.models.Module')>",
-            "docstring": "Representation of a documented Python module or package.\n\nA ``Module`` stores metadata about the module itself and maintains a\ncollection of top-level documentation objects discovered during\nintrospection.\n\nAttributes:\n    path: Dotted import path of the module.\n    docstring: Module-level documentation string, if present.\n    members: Mapping of object names to their corresponding\n        ``DocObject`` representations.",
+            "docstring": "Represents a documented Python module or package.\n\nAttributes:\n    path: Dotted import path of the module.\n    docstring: Module-level docstring content.\n    members: Dictionary mapping object names to their DocObject representations.",
             "members": {
               "path": {
                 "name": "path",
@@ -130,21 +130,21 @@
                 "kind": "function",
                 "path": "docforge.loaders.griffe_loader.Module.add_object",
                 "signature": "<bound method Alias.signature of Alias('add_object', 'docforge.models.module.Module.add_object')>",
-                "docstring": "Add a documented object to the module.\n\nArgs:\n    obj: Documentation object to register as a top-level\n        member of the module."
+                "docstring": "Add a documented object to the module.\n\nArgs:\n    obj: The object to add."
               },
               "get_object": {
                 "name": "get_object",
                 "kind": "function",
                 "path": "docforge.loaders.griffe_loader.Module.get_object",
                 "signature": "<bound method Alias.signature of Alias('get_object', 'docforge.models.module.Module.get_object')>",
-                "docstring": "Retrieve a documented object by name.\n\nArgs:\n    name: Name of the object to retrieve.\n\nReturns:\n    The corresponding ``DocObject`` instance.\n\nRaises:\n    KeyError: If no object with the given name exists."
+                "docstring": "Retrieve a member object by name.\n\nArgs:\n    name: The name of the object.\n\nReturns:\n    The requested DocObject."
               },
               "get_all_objects": {
                 "name": "get_all_objects",
                 "kind": "function",
                 "path": "docforge.loaders.griffe_loader.Module.get_all_objects",
                 "signature": "<bound method Alias.signature of Alias('get_all_objects', 'docforge.models.module.Module.get_all_objects')>",
-                "docstring": "Return all top-level documentation objects in the module.\n\nReturns:\n    An iterable of ``DocObject`` instances representing the\n    module's public members."
+                "docstring": "Get all top-level objects in the module.\n\nReturns:\n    An iterable of DocObject instances."
               }
             }
           },
@@ -153,7 +153,7 @@
             "kind": "class",
             "path": "docforge.loaders.griffe_loader.Project",
             "signature": "<bound method Alias.signature of Alias('Project', 'docforge.models.Project')>",
-            "docstring": "Representation of a documentation project.\n\nA ``Project`` serves as the root container for all modules discovered during\nintrospection. Each module is stored by its dotted import path.\n\nAttributes:\n    name: Name of the project.\n    modules: Mapping of module paths to ``Module`` instances.",
+            "docstring": "Represents a documentation project, serving as a container for modules.\n\nAttributes:\n    name: Name of the project.\n    modules: Dictionary mapping module paths to Module instances.",
             "members": {
               "name": {
                 "name": "name",
@@ -174,28 +174,28 @@
                 "kind": "function",
                 "path": "docforge.loaders.griffe_loader.Project.add_module",
                 "signature": "<bound method Alias.signature of Alias('add_module', 'docforge.models.project.Project.add_module')>",
-                "docstring": "Register a module in the project.\n\nArgs:\n    module: Module instance to add to the project."
+                "docstring": "Add a module to the project.\n\nArgs:\n    module: The module to add."
               },
               "get_module": {
                 "name": "get_module",
                 "kind": "function",
                 "path": "docforge.loaders.griffe_loader.Project.get_module",
                 "signature": "<bound method Alias.signature of Alias('get_module', 'docforge.models.project.Project.get_module')>",
-                "docstring": "Retrieve a module by its dotted path.\n\nArgs:\n    path: Fully qualified dotted module path (for example ``pkg.module``).\n\nReturns:\n    The corresponding ``Module`` instance.\n\nRaises:\n    KeyError: If the module does not exist in the project."
+                "docstring": "Retrieve a module by its dotted path.\n\nArgs:\n    path: The dotted path of the module (e.g., 'pkg.mod').\n\nReturns:\n    The requested Module."
               },
               "get_all_modules": {
                 "name": "get_all_modules",
                 "kind": "function",
                 "path": "docforge.loaders.griffe_loader.Project.get_all_modules",
                 "signature": "<bound method Alias.signature of Alias('get_all_modules', 'docforge.models.project.Project.get_all_modules')>",
-                "docstring": "Return all modules contained in the project.\n\nReturns:\n    An iterable of ``Module`` instances."
+                "docstring": "Get all modules in the project.\n\nReturns:\n    An iterable of Module objects."
               },
               "get_module_list": {
                 "name": "get_module_list",
                 "kind": "function",
                 "path": "docforge.loaders.griffe_loader.Project.get_module_list",
                 "signature": "<bound method Alias.signature of Alias('get_module_list', 'docforge.models.project.Project.get_module_list')>",
-                "docstring": "Return the list of module import paths.\n\nReturns:\n    A list containing the dotted paths of all modules in the project."
+                "docstring": "Get the list of all module dotted paths.\n\nReturns:\n    A list of module paths."
               }
             }
           },
@@ -204,7 +204,7 @@
             "kind": "class",
             "path": "docforge.loaders.griffe_loader.DocObject",
             "signature": "<bound method Alias.signature of Alias('DocObject', 'docforge.models.DocObject')>",
-            "docstring": "Representation of a documented Python object.\n\nA ``DocObject`` models a single Python entity discovered during\nintrospection. Objects may contain nested members, allowing the structure\nof modules, classes, and other containers to be represented recursively.\n\nAttributes:\n    name: Local name of the object.\n    kind: Type of object (for example ``class``, ``function``,\n        ``method``, or ``attribute``).\n    path: Fully qualified dotted path to the object.\n    signature: Callable signature if the object represents a callable.\n    docstring: Raw docstring text extracted from the source code.\n    members: Mapping of member names to child ``DocObject`` instances.",
+            "docstring": "Represents a documented Python object (class, function, method, etc.).\n\nAttributes:\n    name: Local name of the object.\n    kind: Type of object (e.g., 'class', 'function', 'attribute').\n    path: Full dotted import path to the object.\n    signature: Callable signature, if applicable.\n    docstring: Raw docstring content extracted from the source.\n    members: Dictionary mapping member names to their DocObject representations.",
             "members": {
               "name": {
                 "name": "name",
@@ -253,21 +253,21 @@
                 "kind": "function",
                 "path": "docforge.loaders.griffe_loader.DocObject.add_member",
                 "signature": "<bound method Alias.signature of Alias('add_member', 'docforge.models.object.DocObject.add_member')>",
-                "docstring": "Add a child documentation object.\n\nThis is typically used when attaching methods to classes or\nnested objects to their parent containers.\n\nArgs:\n    obj: Documentation object to add as a member."
+                "docstring": "Add a child member to this object (e.g., a method to a class).\n\nArgs:\n    obj: The child DocObject to add."
               },
               "get_member": {
                 "name": "get_member",
                 "kind": "function",
                 "path": "docforge.loaders.griffe_loader.DocObject.get_member",
                 "signature": "<bound method Alias.signature of Alias('get_member', 'docforge.models.object.DocObject.get_member')>",
-                "docstring": "Retrieve a member object by name.\n\nArgs:\n    name: Name of the member to retrieve.\n\nReturns:\n    The corresponding ``DocObject`` instance.\n\nRaises:\n    KeyError: If the member does not exist."
+                "docstring": "Retrieve a child member by name.\n\nArgs:\n    name: The name of the member.\n\nReturns:\n    The requested DocObject."
               },
               "get_all_members": {
                 "name": "get_all_members",
                 "kind": "function",
                 "path": "docforge.loaders.griffe_loader.DocObject.get_all_members",
                 "signature": "<bound method Alias.signature of Alias('get_all_members', 'docforge.models.object.DocObject.get_all_members')>",
-                "docstring": "Return all child members of the object.\n\nReturns:\n    An iterable of ``DocObject`` instances representing nested members."
+                "docstring": "Get all members of this object.\n\nReturns:\n    An iterable of child DocObject instances."
               }
             }
           },
@@ -282,29 +282,29 @@
             "name": "discover_module_paths",
             "kind": "function",
             "path": "docforge.loaders.griffe_loader.discover_module_paths",
-            "signature": "<bound method Function.signature of Function('discover_module_paths', 26, 73)>",
-            "docstring": "Discover Python modules within a package directory.\n\nThe function scans the filesystem for ``.py`` files inside the specified\npackage and converts them into dotted module import paths.\n\nDiscovery rules:\n\n- Directories containing ``__init__.py`` are treated as packages.\n- Each ``.py`` file is treated as a module.\n- Results are returned as dotted import paths.\n\nArgs:\n    module_name: Top-level package name to discover modules from.\n    project_root: Root directory used to resolve module paths. If not\n        provided, the current working directory is used.\n\nReturns:\n    A sorted list of unique dotted module import paths.\n\nRaises:\n    FileNotFoundError: If the specified package directory does not exist."
+            "signature": "<bound method Function.signature of Function('discover_module_paths', 23, 62)>",
+            "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."
           },
           "GriffeLoader": {
             "name": "GriffeLoader",
             "kind": "class",
             "path": "docforge.loaders.griffe_loader.GriffeLoader",
-            "signature": "<bound method Class.signature of Class('GriffeLoader', 76, 264)>",
-            "docstring": "Load Python modules using Griffe and convert them into doc-forge models.\n\nThis loader uses the Griffe introspection engine to analyze Python source\ncode and transform the extracted information into ``Project``, ``Module``,\nand ``DocObject`` instances used by doc-forge.",
+            "signature": "<bound method Class.signature of Class('GriffeLoader', 65, 224)>",
+            "docstring": "Loads Python modules and extracts documentation using the Griffe introspection engine.",
             "members": {
               "load_project": {
                 "name": "load_project",
                 "kind": "function",
                 "path": "docforge.loaders.griffe_loader.GriffeLoader.load_project",
-                "signature": "<bound method Function.signature of Function('load_project', 97, 144)>",
-                "docstring": "Load multiple modules and assemble them into a Project model.\n\nEach module path is introspected and converted into a ``Module``\ninstance. All modules are then aggregated into a single ``Project``\nobject.\n\nArgs:\n    module_paths: List of dotted module import paths to load.\n    project_name: Optional override for the project name. Defaults\n        to the top-level name of the first module.\n    skip_import_errors: If True, modules that fail to load will be\n        skipped instead of raising an error.\n\nReturns:\n    A populated ``Project`` instance containing the loaded modules.\n\nRaises:\n    ValueError: If no module paths are provided.\n    ImportError: If a module fails to load and\n        ``skip_import_errors`` is False."
+                "signature": "<bound method Function.signature of Function('load_project', 79, 115)>",
+                "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.loaders.griffe_loader.GriffeLoader.load_module",
-                "signature": "<bound method Function.signature of Function('load_module', 146, 162)>",
-                "docstring": "Load and convert a single Python module.\n\nThe module is introspected using Griffe and then transformed into\na doc-forge ``Module`` model.\n\nArgs:\n    path: Dotted import path of the module.\n\nReturns:\n    A populated ``Module`` instance."
+                "signature": "<bound method Function.signature of Function('load_module', 117, 130)>",
+                "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."
               }
             }
           }

mcp_docs/modules/docforge.models.json

@@ -2,14 +2,14 @@
   "module": "docforge.models",
   "content": {
     "path": "docforge.models",
-    "docstring": "Model layer for doc-forge.\n\nThe ``docforge.models`` package defines the core data structures used to\nrepresent Python source code as a structured documentation model.\n\n---\n\nOverview\n--------\n\nThe model layer forms the central intermediate representation used throughout\ndoc-forge. Python modules and objects discovered during introspection are\nconverted into a hierarchy of documentation models that can later be rendered\ninto different documentation formats.\n\nKey components:\n\n- **Project** – Root container representing an entire documented codebase.\n- **Module** – Representation of a Python module or package containing\n  documented members.\n- **DocObject** – Recursive structure representing Python objects such as\n  classes, functions, methods, and attributes.\n\nThese models are intentionally **renderer-agnostic**, allowing the same\ndocumentation structure to be transformed into multiple output formats\n(e.g., MkDocs, MCP, or other renderers).\n\n---",
+    "docstring": "# Model Layer\n\nThe `docforge.models` package provides the core data structures used to represent\nPython source code in a documentation-focused hierarchy.\n\n## Key Components\n\n- **Project**: The root container for all documented modules.\n- **Module**: Represents a Python module or package, containing members.\n- **DocObject**: A recursive structure for classes, functions, and attributes.\n\nThese classes are designed to be renderer-agnostic, allowing the same internal\nrepresentation to be transformed into various output formats (currently MkDocs).",
     "objects": {
       "Project": {
         "name": "Project",
         "kind": "class",
         "path": "docforge.models.Project",
         "signature": "<bound method Alias.signature of Alias('Project', 'docforge.models.project.Project')>",
-        "docstring": "Representation of a documentation project.\n\nA ``Project`` serves as the root container for all modules discovered during\nintrospection. Each module is stored by its dotted import path.\n\nAttributes:\n    name: Name of the project.\n    modules: Mapping of module paths to ``Module`` instances.",
+        "docstring": "Represents a documentation project, serving as a container for modules.\n\nAttributes:\n    name: Name of the project.\n    modules: Dictionary mapping module paths to Module instances.",
         "members": {
           "name": {
             "name": "name",
@@ -30,28 +30,28 @@
             "kind": "function",
             "path": "docforge.models.Project.add_module",
             "signature": "<bound method Alias.signature of Alias('add_module', 'docforge.models.project.Project.add_module')>",
-            "docstring": "Register a module in the project.\n\nArgs:\n    module: Module instance to add to the project."
+            "docstring": "Add a module to the project.\n\nArgs:\n    module: The module to add."
           },
           "get_module": {
             "name": "get_module",
             "kind": "function",
             "path": "docforge.models.Project.get_module",
             "signature": "<bound method Alias.signature of Alias('get_module', 'docforge.models.project.Project.get_module')>",
-            "docstring": "Retrieve a module by its dotted path.\n\nArgs:\n    path: Fully qualified dotted module path (for example ``pkg.module``).\n\nReturns:\n    The corresponding ``Module`` instance.\n\nRaises:\n    KeyError: If the module does not exist in the project."
+            "docstring": "Retrieve a module by its dotted path.\n\nArgs:\n    path: The dotted path of the module (e.g., 'pkg.mod').\n\nReturns:\n    The requested Module."
           },
           "get_all_modules": {
             "name": "get_all_modules",
             "kind": "function",
             "path": "docforge.models.Project.get_all_modules",
             "signature": "<bound method Alias.signature of Alias('get_all_modules', 'docforge.models.project.Project.get_all_modules')>",
-            "docstring": "Return all modules contained in the project.\n\nReturns:\n    An iterable of ``Module`` instances."
+            "docstring": "Get all modules in the project.\n\nReturns:\n    An iterable of Module objects."
           },
           "get_module_list": {
             "name": "get_module_list",
             "kind": "function",
             "path": "docforge.models.Project.get_module_list",
             "signature": "<bound method Alias.signature of Alias('get_module_list', 'docforge.models.project.Project.get_module_list')>",
-            "docstring": "Return the list of module import paths.\n\nReturns:\n    A list containing the dotted paths of all modules in the project."
+            "docstring": "Get the list of all module dotted paths.\n\nReturns:\n    A list of module paths."
           }
         }
       },
@@ -60,7 +60,7 @@
         "kind": "class",
         "path": "docforge.models.Module",
         "signature": "<bound method Alias.signature of Alias('Module', 'docforge.models.module.Module')>",
-        "docstring": "Representation of a documented Python module or package.\n\nA ``Module`` stores metadata about the module itself and maintains a\ncollection of top-level documentation objects discovered during\nintrospection.\n\nAttributes:\n    path: Dotted import path of the module.\n    docstring: Module-level documentation string, if present.\n    members: Mapping of object names to their corresponding\n        ``DocObject`` representations.",
+        "docstring": "Represents a documented Python module or package.\n\nAttributes:\n    path: Dotted import path of the module.\n    docstring: Module-level docstring content.\n    members: Dictionary mapping object names to their DocObject representations.",
         "members": {
           "path": {
             "name": "path",
@@ -88,21 +88,21 @@
             "kind": "function",
             "path": "docforge.models.Module.add_object",
             "signature": "<bound method Alias.signature of Alias('add_object', 'docforge.models.module.Module.add_object')>",
-            "docstring": "Add a documented object to the module.\n\nArgs:\n    obj: Documentation object to register as a top-level\n        member of the module."
+            "docstring": "Add a documented object to the module.\n\nArgs:\n    obj: The object to add."
           },
           "get_object": {
             "name": "get_object",
             "kind": "function",
             "path": "docforge.models.Module.get_object",
             "signature": "<bound method Alias.signature of Alias('get_object', 'docforge.models.module.Module.get_object')>",
-            "docstring": "Retrieve a documented object by name.\n\nArgs:\n    name: Name of the object to retrieve.\n\nReturns:\n    The corresponding ``DocObject`` instance.\n\nRaises:\n    KeyError: If no object with the given name exists."
+            "docstring": "Retrieve a member object by name.\n\nArgs:\n    name: The name of the object.\n\nReturns:\n    The requested DocObject."
           },
           "get_all_objects": {
             "name": "get_all_objects",
             "kind": "function",
             "path": "docforge.models.Module.get_all_objects",
             "signature": "<bound method Alias.signature of Alias('get_all_objects', 'docforge.models.module.Module.get_all_objects')>",
-            "docstring": "Return all top-level documentation objects in the module.\n\nReturns:\n    An iterable of ``DocObject`` instances representing the\n    module's public members."
+            "docstring": "Get all top-level objects in the module.\n\nReturns:\n    An iterable of DocObject instances."
           }
         }
       },
@@ -111,7 +111,7 @@
         "kind": "class",
         "path": "docforge.models.DocObject",
         "signature": "<bound method Alias.signature of Alias('DocObject', 'docforge.models.object.DocObject')>",
-        "docstring": "Representation of a documented Python object.\n\nA ``DocObject`` models a single Python entity discovered during\nintrospection. Objects may contain nested members, allowing the structure\nof modules, classes, and other containers to be represented recursively.\n\nAttributes:\n    name: Local name of the object.\n    kind: Type of object (for example ``class``, ``function``,\n        ``method``, or ``attribute``).\n    path: Fully qualified dotted path to the object.\n    signature: Callable signature if the object represents a callable.\n    docstring: Raw docstring text extracted from the source code.\n    members: Mapping of member names to child ``DocObject`` instances.",
+        "docstring": "Represents a documented Python object (class, function, method, etc.).\n\nAttributes:\n    name: Local name of the object.\n    kind: Type of object (e.g., 'class', 'function', 'attribute').\n    path: Full dotted import path to the object.\n    signature: Callable signature, if applicable.\n    docstring: Raw docstring content extracted from the source.\n    members: Dictionary mapping member names to their DocObject representations.",
         "members": {
           "name": {
             "name": "name",
@@ -160,21 +160,21 @@
             "kind": "function",
             "path": "docforge.models.DocObject.add_member",
             "signature": "<bound method Alias.signature of Alias('add_member', 'docforge.models.object.DocObject.add_member')>",
-            "docstring": "Add a child documentation object.\n\nThis is typically used when attaching methods to classes or\nnested objects to their parent containers.\n\nArgs:\n    obj: Documentation object to add as a member."
+            "docstring": "Add a child member to this object (e.g., a method to a class).\n\nArgs:\n    obj: The child DocObject to add."
           },
           "get_member": {
             "name": "get_member",
             "kind": "function",
             "path": "docforge.models.DocObject.get_member",
             "signature": "<bound method Alias.signature of Alias('get_member', 'docforge.models.object.DocObject.get_member')>",
-            "docstring": "Retrieve a member object by name.\n\nArgs:\n    name: Name of the member to retrieve.\n\nReturns:\n    The corresponding ``DocObject`` instance.\n\nRaises:\n    KeyError: If the member does not exist."
+            "docstring": "Retrieve a child member by name.\n\nArgs:\n    name: The name of the member.\n\nReturns:\n    The requested DocObject."
           },
           "get_all_members": {
             "name": "get_all_members",
             "kind": "function",
             "path": "docforge.models.DocObject.get_all_members",
             "signature": "<bound method Alias.signature of Alias('get_all_members', 'docforge.models.object.DocObject.get_all_members')>",
-            "docstring": "Return all child members of the object.\n\nReturns:\n    An iterable of ``DocObject`` instances representing nested members."
+            "docstring": "Get all members of this object.\n\nReturns:\n    An iterable of child DocObject instances."
           }
         }
       },
@@ -183,7 +183,7 @@
         "kind": "module",
         "path": "docforge.models.module",
         "signature": null,
-        "docstring": "Documentation model representing a Python module or package.\n\nThis module defines the ``Module`` class used in the doc-forge documentation\nmodel. A ``Module`` acts as a container for top-level documented objects\n(classes, functions, variables, and other members) discovered during\nintrospection.",
+        "docstring": "This module defines the Module class, which represents a Python module or package\nin the doc-forge documentation models. It acts as a container for top-level\ndocumented objects.",
         "members": {
           "Dict": {
             "name": "Dict",
@@ -211,7 +211,7 @@
             "kind": "class",
             "path": "docforge.models.module.DocObject",
             "signature": "<bound method Alias.signature of Alias('DocObject', 'docforge.models.object.DocObject')>",
-            "docstring": "Representation of a documented Python object.\n\nA ``DocObject`` models a single Python entity discovered during\nintrospection. Objects may contain nested members, allowing the structure\nof modules, classes, and other containers to be represented recursively.\n\nAttributes:\n    name: Local name of the object.\n    kind: Type of object (for example ``class``, ``function``,\n        ``method``, or ``attribute``).\n    path: Fully qualified dotted path to the object.\n    signature: Callable signature if the object represents a callable.\n    docstring: Raw docstring text extracted from the source code.\n    members: Mapping of member names to child ``DocObject`` instances.",
+            "docstring": "Represents a documented Python object (class, function, method, etc.).\n\nAttributes:\n    name: Local name of the object.\n    kind: Type of object (e.g., 'class', 'function', 'attribute').\n    path: Full dotted import path to the object.\n    signature: Callable signature, if applicable.\n    docstring: Raw docstring content extracted from the source.\n    members: Dictionary mapping member names to their DocObject representations.",
             "members": {
               "name": {
                 "name": "name",
@@ -260,21 +260,21 @@
                 "kind": "function",
                 "path": "docforge.models.module.DocObject.add_member",
                 "signature": "<bound method Alias.signature of Alias('add_member', 'docforge.models.object.DocObject.add_member')>",
-                "docstring": "Add a child documentation object.\n\nThis is typically used when attaching methods to classes or\nnested objects to their parent containers.\n\nArgs:\n    obj: Documentation object to add as a member."
+                "docstring": "Add a child member to this object (e.g., a method to a class).\n\nArgs:\n    obj: The child DocObject to add."
               },
               "get_member": {
                 "name": "get_member",
                 "kind": "function",
                 "path": "docforge.models.module.DocObject.get_member",
                 "signature": "<bound method Alias.signature of Alias('get_member', 'docforge.models.object.DocObject.get_member')>",
-                "docstring": "Retrieve a member object by name.\n\nArgs:\n    name: Name of the member to retrieve.\n\nReturns:\n    The corresponding ``DocObject`` instance.\n\nRaises:\n    KeyError: If the member does not exist."
+                "docstring": "Retrieve a child member by name.\n\nArgs:\n    name: The name of the member.\n\nReturns:\n    The requested DocObject."
               },
               "get_all_members": {
                 "name": "get_all_members",
                 "kind": "function",
                 "path": "docforge.models.module.DocObject.get_all_members",
                 "signature": "<bound method Alias.signature of Alias('get_all_members', 'docforge.models.object.DocObject.get_all_members')>",
-                "docstring": "Return all child members of the object.\n\nReturns:\n    An iterable of ``DocObject`` instances representing nested members."
+                "docstring": "Get all members of this object.\n\nReturns:\n    An iterable of child DocObject instances."
               }
             }
           },
@@ -282,8 +282,8 @@
             "name": "Module",
             "kind": "class",
             "path": "docforge.models.module.Module",
-            "signature": "<bound method Class.signature of Class('Module', 15, 79)>",
-            "docstring": "Representation of a documented Python module or package.\n\nA ``Module`` stores metadata about the module itself and maintains a\ncollection of top-level documentation objects discovered during\nintrospection.\n\nAttributes:\n    path: Dotted import path of the module.\n    docstring: Module-level documentation string, if present.\n    members: Mapping of object names to their corresponding\n        ``DocObject`` representations.",
+            "signature": "<bound method Class.signature of Class('Module', 12, 66)>",
+            "docstring": "Represents a documented Python module or package.\n\nAttributes:\n    path: Dotted import path of the module.\n    docstring: Module-level docstring content.\n    members: Dictionary mapping object names to their DocObject representations.",
             "members": {
               "path": {
                 "name": "path",
@@ -310,22 +310,22 @@
                 "name": "add_object",
                 "kind": "function",
                 "path": "docforge.models.module.Module.add_object",
-                "signature": "<bound method Function.signature of Function('add_object', 46, 54)>",
-                "docstring": "Add a documented object to the module.\n\nArgs:\n    obj: Documentation object to register as a top-level\n        member of the module."
+                "signature": "<bound method Function.signature of Function('add_object', 38, 45)>",
+                "docstring": "Add a documented object to the module.\n\nArgs:\n    obj: The object to add."
               },
               "get_object": {
                 "name": "get_object",
                 "kind": "function",
                 "path": "docforge.models.module.Module.get_object",
-                "signature": "<bound method Function.signature of Function('get_object', 56, 69)>",
-                "docstring": "Retrieve a documented object by name.\n\nArgs:\n    name: Name of the object to retrieve.\n\nReturns:\n    The corresponding ``DocObject`` instance.\n\nRaises:\n    KeyError: If no object with the given name exists."
+                "signature": "<bound method Function.signature of Function('get_object', 47, 57)>",
+                "docstring": "Retrieve a member object by name.\n\nArgs:\n    name: The name of the object.\n\nReturns:\n    The requested DocObject."
               },
               "get_all_objects": {
                 "name": "get_all_objects",
                 "kind": "function",
                 "path": "docforge.models.module.Module.get_all_objects",
-                "signature": "<bound method Function.signature of Function('get_all_objects', 71, 79)>",
-                "docstring": "Return all top-level documentation objects in the module.\n\nReturns:\n    An iterable of ``DocObject`` instances representing the\n    module's public members."
+                "signature": "<bound method Function.signature of Function('get_all_objects', 59, 66)>",
+                "docstring": "Get all top-level objects in the module.\n\nReturns:\n    An iterable of DocObject instances."
               }
             }
           }
@@ -336,7 +336,7 @@
         "kind": "module",
         "path": "docforge.models.object",
         "signature": null,
-        "docstring": "Documentation model representing individual Python objects.\n\nThis module defines the ``DocObject`` class, the fundamental recursive unit of\nthe doc-forge documentation model. Each ``DocObject`` represents a Python\nentity such as a class, function, method, or attribute, and may contain nested\nmembers that form a hierarchical documentation structure.",
+        "docstring": "This module defines the DocObject class, the fundamental recursive unit of the\ndoc-forge documentation models. A DocObject represents a single Python entity\n(class, function, method, or attribute) and its nested members.",
         "members": {
           "Dict": {
             "name": "Dict",
@@ -363,8 +363,8 @@
             "name": "DocObject",
             "kind": "class",
             "path": "docforge.models.object.DocObject",
-            "signature": "<bound method Class.signature of Class('DocObject', 13, 90)>",
-            "docstring": "Representation of a documented Python object.\n\nA ``DocObject`` models a single Python entity discovered during\nintrospection. Objects may contain nested members, allowing the structure\nof modules, classes, and other containers to be represented recursively.\n\nAttributes:\n    name: Local name of the object.\n    kind: Type of object (for example ``class``, ``function``,\n        ``method``, or ``attribute``).\n    path: Fully qualified dotted path to the object.\n    signature: Callable signature if the object represents a callable.\n    docstring: Raw docstring text extracted from the source code.\n    members: Mapping of member names to child ``DocObject`` instances.",
+            "signature": "<bound method Class.signature of Class('DocObject', 10, 76)>",
+            "docstring": "Represents a documented Python object (class, function, method, etc.).\n\nAttributes:\n    name: Local name of the object.\n    kind: Type of object (e.g., 'class', 'function', 'attribute').\n    path: Full dotted import path to the object.\n    signature: Callable signature, if applicable.\n    docstring: Raw docstring content extracted from the source.\n    members: Dictionary mapping member names to their DocObject representations.",
             "members": {
               "name": {
                 "name": "name",
@@ -412,22 +412,22 @@
                 "name": "add_member",
                 "kind": "function",
                 "path": "docforge.models.object.DocObject.add_member",
-                "signature": "<bound method Function.signature of Function('add_member', 56, 66)>",
-                "docstring": "Add a child documentation object.\n\nThis is typically used when attaching methods to classes or\nnested objects to their parent containers.\n\nArgs:\n    obj: Documentation object to add as a member."
+                "signature": "<bound method Function.signature of Function('add_member', 48, 55)>",
+                "docstring": "Add a child member to this object (e.g., a method to a class).\n\nArgs:\n    obj: The child DocObject to add."
               },
               "get_member": {
                 "name": "get_member",
                 "kind": "function",
                 "path": "docforge.models.object.DocObject.get_member",
-                "signature": "<bound method Function.signature of Function('get_member', 68, 81)>",
-                "docstring": "Retrieve a member object by name.\n\nArgs:\n    name: Name of the member to retrieve.\n\nReturns:\n    The corresponding ``DocObject`` instance.\n\nRaises:\n    KeyError: If the member does not exist."
+                "signature": "<bound method Function.signature of Function('get_member', 57, 67)>",
+                "docstring": "Retrieve a child member by name.\n\nArgs:\n    name: The name of the member.\n\nReturns:\n    The requested DocObject."
               },
               "get_all_members": {
                 "name": "get_all_members",
                 "kind": "function",
                 "path": "docforge.models.object.DocObject.get_all_members",
-                "signature": "<bound method Function.signature of Function('get_all_members', 83, 90)>",
-                "docstring": "Return all child members of the object.\n\nReturns:\n    An iterable of ``DocObject`` instances representing nested members."
+                "signature": "<bound method Function.signature of Function('get_all_members', 69, 76)>",
+                "docstring": "Get all members of this object.\n\nReturns:\n    An iterable of child DocObject instances."
               }
             }
           }
@@ -438,7 +438,7 @@
         "kind": "module",
         "path": "docforge.models.project",
         "signature": null,
-        "docstring": "Documentation model representing a project.\n\nThis module defines the ``Project`` class, the top-level container used by\ndoc-forge to represent a documented codebase. A ``Project`` aggregates multiple\nmodules and provides access to them through a unified interface.",
+        "docstring": "This module defines the Project class, the top-level container for a documented\nproject. It aggregates multiple Module instances into a single named entity.",
         "members": {
           "Dict": {
             "name": "Dict",
@@ -459,7 +459,7 @@
             "kind": "class",
             "path": "docforge.models.project.Module",
             "signature": "<bound method Alias.signature of Alias('Module', 'docforge.models.module.Module')>",
-            "docstring": "Representation of a documented Python module or package.\n\nA ``Module`` stores metadata about the module itself and maintains a\ncollection of top-level documentation objects discovered during\nintrospection.\n\nAttributes:\n    path: Dotted import path of the module.\n    docstring: Module-level documentation string, if present.\n    members: Mapping of object names to their corresponding\n        ``DocObject`` representations.",
+            "docstring": "Represents a documented Python module or package.\n\nAttributes:\n    path: Dotted import path of the module.\n    docstring: Module-level docstring content.\n    members: Dictionary mapping object names to their DocObject representations.",
             "members": {
               "path": {
                 "name": "path",
@@ -487,21 +487,21 @@
                 "kind": "function",
                 "path": "docforge.models.project.Module.add_object",
                 "signature": "<bound method Alias.signature of Alias('add_object', 'docforge.models.module.Module.add_object')>",
-                "docstring": "Add a documented object to the module.\n\nArgs:\n    obj: Documentation object to register as a top-level\n        member of the module."
+                "docstring": "Add a documented object to the module.\n\nArgs:\n    obj: The object to add."
               },
               "get_object": {
                 "name": "get_object",
                 "kind": "function",
                 "path": "docforge.models.project.Module.get_object",
                 "signature": "<bound method Alias.signature of Alias('get_object', 'docforge.models.module.Module.get_object')>",
-                "docstring": "Retrieve a documented object by name.\n\nArgs:\n    name: Name of the object to retrieve.\n\nReturns:\n    The corresponding ``DocObject`` instance.\n\nRaises:\n    KeyError: If no object with the given name exists."
+                "docstring": "Retrieve a member object by name.\n\nArgs:\n    name: The name of the object.\n\nReturns:\n    The requested DocObject."
               },
               "get_all_objects": {
                 "name": "get_all_objects",
                 "kind": "function",
                 "path": "docforge.models.project.Module.get_all_objects",
                 "signature": "<bound method Alias.signature of Alias('get_all_objects', 'docforge.models.module.Module.get_all_objects')>",
-                "docstring": "Return all top-level documentation objects in the module.\n\nReturns:\n    An iterable of ``DocObject`` instances representing the\n    module's public members."
+                "docstring": "Get all top-level objects in the module.\n\nReturns:\n    An iterable of DocObject instances."
               }
             }
           },
@@ -509,8 +509,8 @@
             "name": "Project",
             "kind": "class",
             "path": "docforge.models.project.Project",
-            "signature": "<bound method Class.signature of Class('Project', 14, 76)>",
-            "docstring": "Representation of a documentation project.\n\nA ``Project`` serves as the root container for all modules discovered during\nintrospection. Each module is stored by its dotted import path.\n\nAttributes:\n    name: Name of the project.\n    modules: Mapping of module paths to ``Module`` instances.",
+            "signature": "<bound method Class.signature of Class('Project', 11, 67)>",
+            "docstring": "Represents a documentation project, serving as a container for modules.\n\nAttributes:\n    name: Name of the project.\n    modules: Dictionary mapping module paths to Module instances.",
             "members": {
               "name": {
                 "name": "name",
@@ -530,29 +530,29 @@
                 "name": "add_module",
                 "kind": "function",
                 "path": "docforge.models.project.Project.add_module",
-                "signature": "<bound method Function.signature of Function('add_module', 36, 43)>",
-                "docstring": "Register a module in the project.\n\nArgs:\n    module: Module instance to add to the project."
+                "signature": "<bound method Function.signature of Function('add_module', 30, 37)>",
+                "docstring": "Add a module to the project.\n\nArgs:\n    module: The module to add."
               },
               "get_module": {
                 "name": "get_module",
                 "kind": "function",
                 "path": "docforge.models.project.Project.get_module",
-                "signature": "<bound method Function.signature of Function('get_module', 45, 58)>",
-                "docstring": "Retrieve a module by its dotted path.\n\nArgs:\n    path: Fully qualified dotted module path (for example ``pkg.module``).\n\nReturns:\n    The corresponding ``Module`` instance.\n\nRaises:\n    KeyError: If the module does not exist in the project."
+                "signature": "<bound method Function.signature of Function('get_module', 39, 49)>",
+                "docstring": "Retrieve a module by its dotted path.\n\nArgs:\n    path: The dotted path of the module (e.g., 'pkg.mod').\n\nReturns:\n    The requested Module."
               },
               "get_all_modules": {
                 "name": "get_all_modules",
                 "kind": "function",
                 "path": "docforge.models.project.Project.get_all_modules",
-                "signature": "<bound method Function.signature of Function('get_all_modules', 60, 67)>",
-                "docstring": "Return all modules contained in the project.\n\nReturns:\n    An iterable of ``Module`` instances."
+                "signature": "<bound method Function.signature of Function('get_all_modules', 51, 58)>",
+                "docstring": "Get all modules in the project.\n\nReturns:\n    An iterable of Module objects."
               },
               "get_module_list": {
                 "name": "get_module_list",
                 "kind": "function",
                 "path": "docforge.models.project.Project.get_module_list",
-                "signature": "<bound method Function.signature of Function('get_module_list', 69, 76)>",
-                "docstring": "Return the list of module import paths.\n\nReturns:\n    A list containing the dotted paths of all modules in the project."
+                "signature": "<bound method Function.signature of Function('get_module_list', 60, 67)>",
+                "docstring": "Get the list of all module dotted paths.\n\nReturns:\n    A list of module paths."
               }
             }
           }

mcp_docs/modules/docforge.models.module.json

@@ -2,7 +2,7 @@
   "module": "docforge.models.module",
   "content": {
     "path": "docforge.models.module",
-    "docstring": "Documentation model representing a Python module or package.\n\nThis module defines the ``Module`` class used in the doc-forge documentation\nmodel. A ``Module`` acts as a container for top-level documented objects\n(classes, functions, variables, and other members) discovered during\nintrospection.",
+    "docstring": "This module defines the Module class, which represents a Python module or package\nin the doc-forge documentation models. It acts as a container for top-level\ndocumented objects.",
     "objects": {
       "Dict": {
         "name": "Dict",
@@ -30,7 +30,7 @@
         "kind": "class",
         "path": "docforge.models.module.DocObject",
         "signature": "<bound method Alias.signature of Alias('DocObject', 'docforge.models.object.DocObject')>",
-        "docstring": "Representation of a documented Python object.\n\nA ``DocObject`` models a single Python entity discovered during\nintrospection. Objects may contain nested members, allowing the structure\nof modules, classes, and other containers to be represented recursively.\n\nAttributes:\n    name: Local name of the object.\n    kind: Type of object (for example ``class``, ``function``,\n        ``method``, or ``attribute``).\n    path: Fully qualified dotted path to the object.\n    signature: Callable signature if the object represents a callable.\n    docstring: Raw docstring text extracted from the source code.\n    members: Mapping of member names to child ``DocObject`` instances.",
+        "docstring": "Represents a documented Python object (class, function, method, etc.).\n\nAttributes:\n    name: Local name of the object.\n    kind: Type of object (e.g., 'class', 'function', 'attribute').\n    path: Full dotted import path to the object.\n    signature: Callable signature, if applicable.\n    docstring: Raw docstring content extracted from the source.\n    members: Dictionary mapping member names to their DocObject representations.",
         "members": {
           "name": {
             "name": "name",
@@ -79,21 +79,21 @@
             "kind": "function",
             "path": "docforge.models.module.DocObject.add_member",
             "signature": "<bound method Alias.signature of Alias('add_member', 'docforge.models.object.DocObject.add_member')>",
-            "docstring": "Add a child documentation object.\n\nThis is typically used when attaching methods to classes or\nnested objects to their parent containers.\n\nArgs:\n    obj: Documentation object to add as a member."
+            "docstring": "Add a child member to this object (e.g., a method to a class).\n\nArgs:\n    obj: The child DocObject to add."
           },
           "get_member": {
             "name": "get_member",
             "kind": "function",
             "path": "docforge.models.module.DocObject.get_member",
             "signature": "<bound method Alias.signature of Alias('get_member', 'docforge.models.object.DocObject.get_member')>",
-            "docstring": "Retrieve a member object by name.\n\nArgs:\n    name: Name of the member to retrieve.\n\nReturns:\n    The corresponding ``DocObject`` instance.\n\nRaises:\n    KeyError: If the member does not exist."
+            "docstring": "Retrieve a child member by name.\n\nArgs:\n    name: The name of the member.\n\nReturns:\n    The requested DocObject."
           },
           "get_all_members": {
             "name": "get_all_members",
             "kind": "function",
             "path": "docforge.models.module.DocObject.get_all_members",
             "signature": "<bound method Alias.signature of Alias('get_all_members', 'docforge.models.object.DocObject.get_all_members')>",
-            "docstring": "Return all child members of the object.\n\nReturns:\n    An iterable of ``DocObject`` instances representing nested members."
+            "docstring": "Get all members of this object.\n\nReturns:\n    An iterable of child DocObject instances."
           }
         }
       },
@@ -101,8 +101,8 @@
         "name": "Module",
         "kind": "class",
         "path": "docforge.models.module.Module",
-        "signature": "<bound method Class.signature of Class('Module', 15, 79)>",
-        "docstring": "Representation of a documented Python module or package.\n\nA ``Module`` stores metadata about the module itself and maintains a\ncollection of top-level documentation objects discovered during\nintrospection.\n\nAttributes:\n    path: Dotted import path of the module.\n    docstring: Module-level documentation string, if present.\n    members: Mapping of object names to their corresponding\n        ``DocObject`` representations.",
+        "signature": "<bound method Class.signature of Class('Module', 12, 66)>",
+        "docstring": "Represents a documented Python module or package.\n\nAttributes:\n    path: Dotted import path of the module.\n    docstring: Module-level docstring content.\n    members: Dictionary mapping object names to their DocObject representations.",
         "members": {
           "path": {
             "name": "path",
@@ -129,22 +129,22 @@
             "name": "add_object",
             "kind": "function",
             "path": "docforge.models.module.Module.add_object",
-            "signature": "<bound method Function.signature of Function('add_object', 46, 54)>",
-            "docstring": "Add a documented object to the module.\n\nArgs:\n    obj: Documentation object to register as a top-level\n        member of the module."
+            "signature": "<bound method Function.signature of Function('add_object', 38, 45)>",
+            "docstring": "Add a documented object to the module.\n\nArgs:\n    obj: The object to add."
           },
           "get_object": {
             "name": "get_object",
             "kind": "function",
             "path": "docforge.models.module.Module.get_object",
-            "signature": "<bound method Function.signature of Function('get_object', 56, 69)>",
-            "docstring": "Retrieve a documented object by name.\n\nArgs:\n    name: Name of the object to retrieve.\n\nReturns:\n    The corresponding ``DocObject`` instance.\n\nRaises:\n    KeyError: If no object with the given name exists."
+            "signature": "<bound method Function.signature of Function('get_object', 47, 57)>",
+            "docstring": "Retrieve a member object by name.\n\nArgs:\n    name: The name of the object.\n\nReturns:\n    The requested DocObject."
           },
           "get_all_objects": {
             "name": "get_all_objects",
             "kind": "function",
             "path": "docforge.models.module.Module.get_all_objects",
-            "signature": "<bound method Function.signature of Function('get_all_objects', 71, 79)>",
-            "docstring": "Return all top-level documentation objects in the module.\n\nReturns:\n    An iterable of ``DocObject`` instances representing the\n    module's public members."
+            "signature": "<bound method Function.signature of Function('get_all_objects', 59, 66)>",
+            "docstring": "Get all top-level objects in the module.\n\nReturns:\n    An iterable of DocObject instances."
           }
         }
       }

mcp_docs/modules/docforge.models.object.json

@@ -2,7 +2,7 @@
   "module": "docforge.models.object",
   "content": {
     "path": "docforge.models.object",
-    "docstring": "Documentation model representing individual Python objects.\n\nThis module defines the ``DocObject`` class, the fundamental recursive unit of\nthe doc-forge documentation model. Each ``DocObject`` represents a Python\nentity such as a class, function, method, or attribute, and may contain nested\nmembers that form a hierarchical documentation structure.",
+    "docstring": "This module defines the DocObject class, the fundamental recursive unit of the\ndoc-forge documentation models. A DocObject represents a single Python entity\n(class, function, method, or attribute) and its nested members.",
     "objects": {
       "Dict": {
         "name": "Dict",
@@ -29,8 +29,8 @@
         "name": "DocObject",
         "kind": "class",
         "path": "docforge.models.object.DocObject",
-        "signature": "<bound method Class.signature of Class('DocObject', 13, 90)>",
-        "docstring": "Representation of a documented Python object.\n\nA ``DocObject`` models a single Python entity discovered during\nintrospection. Objects may contain nested members, allowing the structure\nof modules, classes, and other containers to be represented recursively.\n\nAttributes:\n    name: Local name of the object.\n    kind: Type of object (for example ``class``, ``function``,\n        ``method``, or ``attribute``).\n    path: Fully qualified dotted path to the object.\n    signature: Callable signature if the object represents a callable.\n    docstring: Raw docstring text extracted from the source code.\n    members: Mapping of member names to child ``DocObject`` instances.",
+        "signature": "<bound method Class.signature of Class('DocObject', 10, 76)>",
+        "docstring": "Represents a documented Python object (class, function, method, etc.).\n\nAttributes:\n    name: Local name of the object.\n    kind: Type of object (e.g., 'class', 'function', 'attribute').\n    path: Full dotted import path to the object.\n    signature: Callable signature, if applicable.\n    docstring: Raw docstring content extracted from the source.\n    members: Dictionary mapping member names to their DocObject representations.",
         "members": {
           "name": {
             "name": "name",
@@ -78,22 +78,22 @@
             "name": "add_member",
             "kind": "function",
             "path": "docforge.models.object.DocObject.add_member",
-            "signature": "<bound method Function.signature of Function('add_member', 56, 66)>",
-            "docstring": "Add a child documentation object.\n\nThis is typically used when attaching methods to classes or\nnested objects to their parent containers.\n\nArgs:\n    obj: Documentation object to add as a member."
+            "signature": "<bound method Function.signature of Function('add_member', 48, 55)>",
+            "docstring": "Add a child member to this object (e.g., a method to a class).\n\nArgs:\n    obj: The child DocObject to add."
           },
           "get_member": {
             "name": "get_member",
             "kind": "function",
             "path": "docforge.models.object.DocObject.get_member",
-            "signature": "<bound method Function.signature of Function('get_member', 68, 81)>",
-            "docstring": "Retrieve a member object by name.\n\nArgs:\n    name: Name of the member to retrieve.\n\nReturns:\n    The corresponding ``DocObject`` instance.\n\nRaises:\n    KeyError: If the member does not exist."
+            "signature": "<bound method Function.signature of Function('get_member', 57, 67)>",
+            "docstring": "Retrieve a child member by name.\n\nArgs:\n    name: The name of the member.\n\nReturns:\n    The requested DocObject."
           },
           "get_all_members": {
             "name": "get_all_members",
             "kind": "function",
             "path": "docforge.models.object.DocObject.get_all_members",
-            "signature": "<bound method Function.signature of Function('get_all_members', 83, 90)>",
-            "docstring": "Return all child members of the object.\n\nReturns:\n    An iterable of ``DocObject`` instances representing nested members."
+            "signature": "<bound method Function.signature of Function('get_all_members', 69, 76)>",
+            "docstring": "Get all members of this object.\n\nReturns:\n    An iterable of child DocObject instances."
           }
         }
       }

mcp_docs/modules/docforge.models.project.json

@@ -2,7 +2,7 @@
   "module": "docforge.models.project",
   "content": {
     "path": "docforge.models.project",
-    "docstring": "Documentation model representing a project.\n\nThis module defines the ``Project`` class, the top-level container used by\ndoc-forge to represent a documented codebase. A ``Project`` aggregates multiple\nmodules and provides access to them through a unified interface.",
+    "docstring": "This module defines the Project class, the top-level container for a documented\nproject. It aggregates multiple Module instances into a single named entity.",
     "objects": {
       "Dict": {
         "name": "Dict",
@@ -23,7 +23,7 @@
         "kind": "class",
         "path": "docforge.models.project.Module",
         "signature": "<bound method Alias.signature of Alias('Module', 'docforge.models.module.Module')>",
-        "docstring": "Representation of a documented Python module or package.\n\nA ``Module`` stores metadata about the module itself and maintains a\ncollection of top-level documentation objects discovered during\nintrospection.\n\nAttributes:\n    path: Dotted import path of the module.\n    docstring: Module-level documentation string, if present.\n    members: Mapping of object names to their corresponding\n        ``DocObject`` representations.",
+        "docstring": "Represents a documented Python module or package.\n\nAttributes:\n    path: Dotted import path of the module.\n    docstring: Module-level docstring content.\n    members: Dictionary mapping object names to their DocObject representations.",
         "members": {
           "path": {
             "name": "path",
@@ -51,21 +51,21 @@
             "kind": "function",
             "path": "docforge.models.project.Module.add_object",
             "signature": "<bound method Alias.signature of Alias('add_object', 'docforge.models.module.Module.add_object')>",
-            "docstring": "Add a documented object to the module.\n\nArgs:\n    obj: Documentation object to register as a top-level\n        member of the module."
+            "docstring": "Add a documented object to the module.\n\nArgs:\n    obj: The object to add."
           },
           "get_object": {
             "name": "get_object",
             "kind": "function",
             "path": "docforge.models.project.Module.get_object",
             "signature": "<bound method Alias.signature of Alias('get_object', 'docforge.models.module.Module.get_object')>",
-            "docstring": "Retrieve a documented object by name.\n\nArgs:\n    name: Name of the object to retrieve.\n\nReturns:\n    The corresponding ``DocObject`` instance.\n\nRaises:\n    KeyError: If no object with the given name exists."
+            "docstring": "Retrieve a member object by name.\n\nArgs:\n    name: The name of the object.\n\nReturns:\n    The requested DocObject."
           },
           "get_all_objects": {
             "name": "get_all_objects",
             "kind": "function",
             "path": "docforge.models.project.Module.get_all_objects",
             "signature": "<bound method Alias.signature of Alias('get_all_objects', 'docforge.models.module.Module.get_all_objects')>",
-            "docstring": "Return all top-level documentation objects in the module.\n\nReturns:\n    An iterable of ``DocObject`` instances representing the\n    module's public members."
+            "docstring": "Get all top-level objects in the module.\n\nReturns:\n    An iterable of DocObject instances."
           }
         }
       },
@@ -73,8 +73,8 @@
         "name": "Project",
         "kind": "class",
         "path": "docforge.models.project.Project",
-        "signature": "<bound method Class.signature of Class('Project', 14, 76)>",
-        "docstring": "Representation of a documentation project.\n\nA ``Project`` serves as the root container for all modules discovered during\nintrospection. Each module is stored by its dotted import path.\n\nAttributes:\n    name: Name of the project.\n    modules: Mapping of module paths to ``Module`` instances.",
+        "signature": "<bound method Class.signature of Class('Project', 11, 67)>",
+        "docstring": "Represents a documentation project, serving as a container for modules.\n\nAttributes:\n    name: Name of the project.\n    modules: Dictionary mapping module paths to Module instances.",
         "members": {
           "name": {
             "name": "name",
@@ -94,29 +94,29 @@
             "name": "add_module",
             "kind": "function",
             "path": "docforge.models.project.Project.add_module",
-            "signature": "<bound method Function.signature of Function('add_module', 36, 43)>",
-            "docstring": "Register a module in the project.\n\nArgs:\n    module: Module instance to add to the project."
+            "signature": "<bound method Function.signature of Function('add_module', 30, 37)>",
+            "docstring": "Add a module to the project.\n\nArgs:\n    module: The module to add."
           },
           "get_module": {
             "name": "get_module",
             "kind": "function",
             "path": "docforge.models.project.Project.get_module",
-            "signature": "<bound method Function.signature of Function('get_module', 45, 58)>",
-            "docstring": "Retrieve a module by its dotted path.\n\nArgs:\n    path: Fully qualified dotted module path (for example ``pkg.module``).\n\nReturns:\n    The corresponding ``Module`` instance.\n\nRaises:\n    KeyError: If the module does not exist in the project."
+            "signature": "<bound method Function.signature of Function('get_module', 39, 49)>",
+            "docstring": "Retrieve a module by its dotted path.\n\nArgs:\n    path: The dotted path of the module (e.g., 'pkg.mod').\n\nReturns:\n    The requested Module."
           },
           "get_all_modules": {
             "name": "get_all_modules",
             "kind": "function",
             "path": "docforge.models.project.Project.get_all_modules",
-            "signature": "<bound method Function.signature of Function('get_all_modules', 60, 67)>",
-            "docstring": "Return all modules contained in the project.\n\nReturns:\n    An iterable of ``Module`` instances."
+            "signature": "<bound method Function.signature of Function('get_all_modules', 51, 58)>",
+            "docstring": "Get all modules in the project.\n\nReturns:\n    An iterable of Module objects."
           },
           "get_module_list": {
             "name": "get_module_list",
             "kind": "function",
             "path": "docforge.models.project.Project.get_module_list",
-            "signature": "<bound method Function.signature of Function('get_module_list', 69, 76)>",
-            "docstring": "Return the list of module import paths.\n\nReturns:\n    A list containing the dotted paths of all modules in the project."
+            "signature": "<bound method Function.signature of Function('get_module_list', 60, 67)>",
+            "docstring": "Get the list of all module dotted paths.\n\nReturns:\n    A list of module paths."
           }
         }
       }

mcp_docs/modules/docforge.nav.json

@@ -2,14 +2,14 @@
   "module": "docforge.nav",
   "content": {
     "path": "docforge.nav",
-    "docstring": "Navigation layer for doc-forge.\n\nThe ``docforge.nav`` package manages the relationship between the logical\ndocumentation structure defined by the user and the physical documentation\nfiles generated on disk.\n\n---\n\nWorkflow\n--------\n\n1. **Specification** – Users define navigation intent in ``docforge.nav.yml``.\n2. **Resolution** – ``resolve_nav`` expands patterns and matches them against\n   generated Markdown files.\n3. **Emission** – ``MkDocsNavEmitter`` converts the resolved structure into\n   the YAML navigation format required by ``mkdocs.yml``.\n\nThis layer separates documentation organization from the underlying source\ncode layout, enabling flexible grouping, ordering, and navigation structures\nindependent of module hierarchy.\n\n---",
+    "docstring": "# Navigation Layer\n\nThe `docforge.nav` package manages the mapping between the logical documentation\nstructure and the physical files on disk.\n\n## Workflow\n\n1.  **Spec Definition**: Users define navigation intent in `docforge.nav.yml`.\n2.  **Resolution**: `resolve_nav` matches patterns in the spec to generated `.md` files.\n3.  **Emission**: `MkDocsNavEmitter` produces the final YAML structure for `mkdocs.yml`.\n\nThis abstraction allows doc-forge to support complex grouping and ordering\nindependently of the source code's physical layout.",
     "objects": {
       "NavSpec": {
         "name": "NavSpec",
         "kind": "class",
         "path": "docforge.nav.NavSpec",
         "signature": "<bound method Alias.signature of Alias('NavSpec', 'docforge.nav.spec.NavSpec')>",
-        "docstring": "Parsed representation of a navigation specification.\n\nA ``NavSpec`` describes the intended documentation navigation layout before\nit is resolved against the filesystem.\n\nAttributes:\n    home: Relative path to the documentation home page (for example\n        ``index.md``).\n    groups: Mapping of navigation group titles to lists of file patterns\n        or glob expressions.",
+        "docstring": "Parsed representation of the docforge navigation specification file.\n\nAttributes:\n    home: Path to the home document (e.g., 'index.md').\n    groups: Mapping of group titles to lists of path patterns/globs.",
         "members": {
           "home": {
             "name": "home",
@@ -30,14 +30,14 @@
             "kind": "function",
             "path": "docforge.nav.NavSpec.load",
             "signature": "<bound method Alias.signature of Alias('load', 'docforge.nav.spec.NavSpec.load')>",
-            "docstring": "Load a navigation specification from a YAML file.\n\nArgs:\n    path: Filesystem path to the navigation specification file.\n\nReturns:\n    A ``NavSpec`` instance representing the parsed configuration.\n\nRaises:\n    FileNotFoundError: If the specified file does not exist.\n    ValueError: If the file contents are not a valid navigation\n        specification."
+            "docstring": "Load a NavSpec from a YAML file.\n\nArgs:\n    path: The filesystem path to the YAML file.\n\nReturns:\n    A NavSpec instance.\n\nRaises:\n    FileNotFoundError: If the path does not exist.\n    ValueError: If the file content is not a valid NavSpec mapping."
           },
           "all_patterns": {
             "name": "all_patterns",
             "kind": "function",
             "path": "docforge.nav.NavSpec.all_patterns",
             "signature": "<bound method Alias.signature of Alias('all_patterns', 'docforge.nav.spec.NavSpec.all_patterns')>",
-            "docstring": "Return all path patterns referenced by the specification.\n\nReturns:\n    A list containing the home document (if defined) and all\n    group pattern entries."
+            "docstring": "Get all path patterns referenced in the specification.\n\nReturns:\n    A list of all patterns (home plus all groups)."
           }
         }
       },
@@ -46,14 +46,14 @@
         "kind": "function",
         "path": "docforge.nav.load_nav_spec",
         "signature": "<bound method Alias.signature of Alias('load_nav_spec', 'docforge.nav.spec.load_nav_spec')>",
-        "docstring": "Load a navigation specification file.\n\nThis helper function reads a YAML navigation file and constructs a\ncorresponding ``NavSpec`` instance.\n\nArgs:\n    path: Path to the navigation specification file.\n\nReturns:\n    A ``NavSpec`` instance representing the parsed specification.\n\nRaises:\n    FileNotFoundError: If the specification file does not exist.\n    ValueError: If the YAML structure is invalid."
+        "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."
       },
       "ResolvedNav": {
         "name": "ResolvedNav",
         "kind": "class",
         "path": "docforge.nav.ResolvedNav",
         "signature": "<bound method Alias.signature of Alias('ResolvedNav', 'docforge.nav.resolver.ResolvedNav')>",
-        "docstring": "Resolved navigation structure.\n\nA ``ResolvedNav`` represents navigation data after glob patterns have been\nexpanded and paths validated against the filesystem.\n\nAttributes:\n    home: Relative path to the documentation home page.\n    groups: Mapping of navigation group titles to lists of resolved\n        documentation file paths.",
+        "docstring": "Represents a navigation structure where all patterns and paths have been\nresolved against the actual filesystem contents.\n\nAttributes:\n    home: Resolved relative path to the home page.\n    groups: Mapping of group titles to lists of absolute or relative Path objects.",
         "members": {
           "home": {
             "name": "home",
@@ -74,7 +74,7 @@
             "kind": "function",
             "path": "docforge.nav.ResolvedNav.all_files",
             "signature": "<bound method Alias.signature of Alias('all_files', 'docforge.nav.resolver.ResolvedNav.all_files')>",
-            "docstring": "Iterate over all files referenced by the navigation structure.\n\nReturns:\n    An iterable of ``Path`` objects representing documentation files.\n\nRaises:\n    RuntimeError: If the home page is defined but the documentation\n        root is not available for resolution."
+            "docstring": "Get an iterable of all resolved files in the navigation structure.\n\nReturns:\n    An iterable of Path objects."
           }
         }
       },
@@ -83,21 +83,21 @@
         "kind": "function",
         "path": "docforge.nav.resolve_nav",
         "signature": "<bound method Alias.signature of Alias('resolve_nav', 'docforge.nav.resolver.resolve_nav')>",
-        "docstring": "Resolve a navigation specification against the filesystem.\n\nThe function expands glob patterns defined in a ``NavSpec`` and verifies\nthat referenced documentation files exist within the documentation root.\n\nArgs:\n    spec: Navigation specification describing documentation layout.\n    docs_root: Root directory containing documentation Markdown files.\n\nReturns:\n    A ``ResolvedNav`` instance containing validated navigation paths.\n\nRaises:\n    FileNotFoundError: If the documentation root does not exist or a\n        navigation pattern does not match any files."
+        "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.nav.MkDocsNavEmitter",
         "signature": "<bound method Alias.signature of Alias('MkDocsNavEmitter', 'docforge.nav.mkdocs.MkDocsNavEmitter')>",
-        "docstring": "Emit MkDocs navigation structures from resolved navigation data.\n\nThe emitter transforms a ``ResolvedNav`` object into the YAML-compatible\nlist structure expected by the MkDocs ``nav`` configuration field.",
+        "docstring": "Emitter responsible for transforming a ResolvedNav into an MkDocs-compatible\nnavigation structure.",
         "members": {
           "emit": {
             "name": "emit",
             "kind": "function",
             "path": "docforge.nav.MkDocsNavEmitter.emit",
             "signature": "<bound method Alias.signature of Alias('emit', 'docforge.nav.mkdocs.MkDocsNavEmitter.emit')>",
-            "docstring": "Generate a navigation structure for ``mkdocs.yml``.\n\nArgs:\n    nav: Resolved navigation data describing documentation groups\n        and their associated Markdown files.\n\nReturns:\n    A list of dictionaries representing the MkDocs navigation layout.\n    Each dictionary maps a navigation label to a page or a list of\n    pages."
+            "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."
           }
         }
       },
@@ -106,7 +106,7 @@
         "kind": "module",
         "path": "docforge.nav.mkdocs",
         "signature": null,
-        "docstring": "MkDocs navigation emitter.\n\nThis module provides the ``MkDocsNavEmitter`` class, which converts a\n``ResolvedNav`` instance into the navigation structure required by the\nMkDocs ``nav`` configuration.",
+        "docstring": "This module provides the MkDocsNavEmitter, which converts a ResolvedNav instance\ninto the specific YAML-ready list structure expected by the MkDocs 'nav'\nconfiguration.",
         "members": {
           "Path": {
             "name": "Path",
@@ -141,7 +141,7 @@
             "kind": "class",
             "path": "docforge.nav.mkdocs.ResolvedNav",
             "signature": "<bound method Alias.signature of Alias('ResolvedNav', 'docforge.nav.resolver.ResolvedNav')>",
-            "docstring": "Resolved navigation structure.\n\nA ``ResolvedNav`` represents navigation data after glob patterns have been\nexpanded and paths validated against the filesystem.\n\nAttributes:\n    home: Relative path to the documentation home page.\n    groups: Mapping of navigation group titles to lists of resolved\n        documentation file paths.",
+            "docstring": "Represents a navigation structure where all patterns and paths have been\nresolved against the actual filesystem contents.\n\nAttributes:\n    home: Resolved relative path to the home page.\n    groups: Mapping of group titles to lists of absolute or relative Path objects.",
             "members": {
               "home": {
                 "name": "home",
@@ -162,7 +162,7 @@
                 "kind": "function",
                 "path": "docforge.nav.mkdocs.ResolvedNav.all_files",
                 "signature": "<bound method Alias.signature of Alias('all_files', 'docforge.nav.resolver.ResolvedNav.all_files')>",
-                "docstring": "Iterate over all files referenced by the navigation structure.\n\nReturns:\n    An iterable of ``Path`` objects representing documentation files.\n\nRaises:\n    RuntimeError: If the home page is defined but the documentation\n        root is not available for resolution."
+                "docstring": "Get an iterable of all resolved files in the navigation structure.\n\nReturns:\n    An iterable of Path objects."
               }
             }
           },
@@ -170,15 +170,15 @@
             "name": "MkDocsNavEmitter",
             "kind": "class",
             "path": "docforge.nav.mkdocs.MkDocsNavEmitter",
-            "signature": "<bound method Class.signature of Class('MkDocsNavEmitter', 15, 81)>",
-            "docstring": "Emit MkDocs navigation structures from resolved navigation data.\n\nThe emitter transforms a ``ResolvedNav`` object into the YAML-compatible\nlist structure expected by the MkDocs ``nav`` configuration field.",
+            "signature": "<bound method Class.signature of Class('MkDocsNavEmitter', 13, 72)>",
+            "docstring": "Emitter responsible for transforming a ResolvedNav into an MkDocs-compatible\nnavigation structure.",
             "members": {
               "emit": {
                 "name": "emit",
                 "kind": "function",
                 "path": "docforge.nav.mkdocs.MkDocsNavEmitter.emit",
-                "signature": "<bound method Function.signature of Function('emit', 23, 51)>",
-                "docstring": "Generate a navigation structure for ``mkdocs.yml``.\n\nArgs:\n    nav: Resolved navigation data describing documentation groups\n        and their associated Markdown files.\n\nReturns:\n    A list of dictionaries representing the MkDocs navigation layout.\n    Each dictionary maps a navigation label to a page or a list of\n    pages."
+                "signature": "<bound method Function.signature of Function('emit', 19, 44)>",
+                "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."
               }
             }
           }
@@ -189,7 +189,7 @@
         "kind": "module",
         "path": "docforge.nav.resolver",
         "signature": null,
-        "docstring": "Navigation resolution utilities.\n\nThis module resolves a ``NavSpec`` against the filesystem by expanding glob\npatterns and validating that referenced documentation files exist.",
+        "docstring": "This module contains the logic for resolving a NavSpec against the physical\nfilesystem. It expands globs and validates that all referenced documents\nactually exist on disk.",
         "members": {
           "Path": {
             "name": "Path",
@@ -231,7 +231,7 @@
             "kind": "class",
             "path": "docforge.nav.resolver.NavSpec",
             "signature": "<bound method Alias.signature of Alias('NavSpec', 'docforge.nav.spec.NavSpec')>",
-            "docstring": "Parsed representation of a navigation specification.\n\nA ``NavSpec`` describes the intended documentation navigation layout before\nit is resolved against the filesystem.\n\nAttributes:\n    home: Relative path to the documentation home page (for example\n        ``index.md``).\n    groups: Mapping of navigation group titles to lists of file patterns\n        or glob expressions.",
+            "docstring": "Parsed representation of the docforge navigation specification file.\n\nAttributes:\n    home: Path to the home document (e.g., 'index.md').\n    groups: Mapping of group titles to lists of path patterns/globs.",
             "members": {
               "home": {
                 "name": "home",
@@ -252,14 +252,14 @@
                 "kind": "function",
                 "path": "docforge.nav.resolver.NavSpec.load",
                 "signature": "<bound method Alias.signature of Alias('load', 'docforge.nav.spec.NavSpec.load')>",
-                "docstring": "Load a navigation specification from a YAML file.\n\nArgs:\n    path: Filesystem path to the navigation specification file.\n\nReturns:\n    A ``NavSpec`` instance representing the parsed configuration.\n\nRaises:\n    FileNotFoundError: If the specified file does not exist.\n    ValueError: If the file contents are not a valid navigation\n        specification."
+                "docstring": "Load a NavSpec from a YAML file.\n\nArgs:\n    path: The filesystem path to the YAML file.\n\nReturns:\n    A NavSpec instance.\n\nRaises:\n    FileNotFoundError: If the path does not exist.\n    ValueError: If the file content is not a valid NavSpec mapping."
               },
               "all_patterns": {
                 "name": "all_patterns",
                 "kind": "function",
                 "path": "docforge.nav.resolver.NavSpec.all_patterns",
                 "signature": "<bound method Alias.signature of Alias('all_patterns', 'docforge.nav.spec.NavSpec.all_patterns')>",
-                "docstring": "Return all path patterns referenced by the specification.\n\nReturns:\n    A list containing the home document (if defined) and all\n    group pattern entries."
+                "docstring": "Get all path patterns referenced in the specification.\n\nReturns:\n    A list of all patterns (home plus all groups)."
               }
             }
           },
@@ -267,8 +267,8 @@
             "name": "ResolvedNav",
             "kind": "class",
             "path": "docforge.nav.resolver.ResolvedNav",
-            "signature": "<bound method Class.signature of Class('ResolvedNav', 16, 65)>",
-            "docstring": "Resolved navigation structure.\n\nA ``ResolvedNav`` represents navigation data after glob patterns have been\nexpanded and paths validated against the filesystem.\n\nAttributes:\n    home: Relative path to the documentation home page.\n    groups: Mapping of navigation group titles to lists of resolved\n        documentation file paths.",
+            "signature": "<bound method Class.signature of Class('ResolvedNav', 15, 56)>",
+            "docstring": "Represents a navigation structure where all patterns and paths have been\nresolved against the actual filesystem contents.\n\nAttributes:\n    home: Resolved relative path to the home page.\n    groups: Mapping of group titles to lists of absolute or relative Path objects.",
             "members": {
               "home": {
                 "name": "home",
@@ -288,8 +288,8 @@
                 "name": "all_files",
                 "kind": "function",
                 "path": "docforge.nav.resolver.ResolvedNav.all_files",
-                "signature": "<bound method Function.signature of Function('all_files', 47, 65)>",
-                "docstring": "Iterate over all files referenced by the navigation structure.\n\nReturns:\n    An iterable of ``Path`` objects representing documentation files.\n\nRaises:\n    RuntimeError: If the home page is defined but the documentation\n        root is not available for resolution."
+                "signature": "<bound method Function.signature of Function('all_files', 43, 56)>",
+                "docstring": "Get an iterable of all resolved files in the navigation structure.\n\nReturns:\n    An iterable of Path objects."
               }
             }
           },
@@ -297,8 +297,8 @@
             "name": "resolve_nav",
             "kind": "function",
             "path": "docforge.nav.resolver.resolve_nav",
-            "signature": "<bound method Function.signature of Function('resolve_nav', 68, 136)>",
-            "docstring": "Resolve a navigation specification against the filesystem.\n\nThe function expands glob patterns defined in a ``NavSpec`` and verifies\nthat referenced documentation files exist within the documentation root.\n\nArgs:\n    spec: Navigation specification describing documentation layout.\n    docs_root: Root directory containing documentation Markdown files.\n\nReturns:\n    A ``ResolvedNav`` instance containing validated navigation paths.\n\nRaises:\n    FileNotFoundError: If the documentation root does not exist or a\n        navigation pattern does not match any files."
+            "signature": "<bound method Function.signature of Function('resolve_nav', 59, 124)>",
+            "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."
           },
           "Optional": {
             "name": "Optional",
@@ -314,7 +314,7 @@
         "kind": "module",
         "path": "docforge.nav.spec",
         "signature": null,
-        "docstring": "Navigation specification model.\n\nThis module defines the ``NavSpec`` class, which represents the navigation\nstructure defined by the user in the doc-forge navigation specification\n(typically ``docforge.nav.yml``).",
+        "docstring": "This module defines the NavSpec class, which represents the user's intent for\ndocumentation navigation as defined in a YAML specification (usually\ndocforge.nav.yml).",
         "members": {
           "Path": {
             "name": "Path",
@@ -355,8 +355,8 @@
             "name": "NavSpec",
             "kind": "class",
             "path": "docforge.nav.spec.NavSpec",
-            "signature": "<bound method Class.signature of Class('NavSpec', 15, 104)>",
-            "docstring": "Parsed representation of a navigation specification.\n\nA ``NavSpec`` describes the intended documentation navigation layout before\nit is resolved against the filesystem.\n\nAttributes:\n    home: Relative path to the documentation home page (for example\n        ``index.md``).\n    groups: Mapping of navigation group titles to lists of file patterns\n        or glob expressions.",
+            "signature": "<bound method Class.signature of Class('NavSpec', 13, 91)>",
+            "docstring": "Parsed representation of the docforge navigation specification file.\n\nAttributes:\n    home: Path to the home document (e.g., 'index.md').\n    groups: Mapping of group titles to lists of path patterns/globs.",
             "members": {
               "home": {
                 "name": "home",
@@ -376,15 +376,15 @@
                 "name": "load",
                 "kind": "function",
                 "path": "docforge.nav.spec.NavSpec.load",
-                "signature": "<bound method Function.signature of Function('load', 45, 86)>",
-                "docstring": "Load a navigation specification from a YAML file.\n\nArgs:\n    path: Filesystem path to the navigation specification file.\n\nReturns:\n    A ``NavSpec`` instance representing the parsed configuration.\n\nRaises:\n    FileNotFoundError: If the specified file does not exist.\n    ValueError: If the file contents are not a valid navigation\n        specification."
+                "signature": "<bound method Function.signature of Function('load', 37, 77)>",
+                "docstring": "Load a NavSpec from a YAML file.\n\nArgs:\n    path: The filesystem path to the YAML file.\n\nReturns:\n    A NavSpec instance.\n\nRaises:\n    FileNotFoundError: If the path does not exist.\n    ValueError: If the file content is not a valid NavSpec mapping."
               },
               "all_patterns": {
                 "name": "all_patterns",
                 "kind": "function",
                 "path": "docforge.nav.spec.NavSpec.all_patterns",
-                "signature": "<bound method Function.signature of Function('all_patterns', 88, 104)>",
-                "docstring": "Return all path patterns referenced by the specification.\n\nReturns:\n    A list containing the home document (if defined) and all\n    group pattern entries."
+                "signature": "<bound method Function.signature of Function('all_patterns', 79, 91)>",
+                "docstring": "Get all path patterns referenced in the specification.\n\nReturns:\n    A list of all patterns (home plus all groups)."
               }
             }
           },
@@ -392,8 +392,8 @@
             "name": "load_nav_spec",
             "kind": "function",
             "path": "docforge.nav.spec.load_nav_spec",
-            "signature": "<bound method Function.signature of Function('load_nav_spec', 107, 135)>",
-            "docstring": "Load a navigation specification file.\n\nThis helper function reads a YAML navigation file and constructs a\ncorresponding ``NavSpec`` instance.\n\nArgs:\n    path: Path to the navigation specification file.\n\nReturns:\n    A ``NavSpec`` instance representing the parsed specification.\n\nRaises:\n    FileNotFoundError: If the specification file does not exist.\n    ValueError: If the YAML structure is invalid."
+            "signature": "<bound method Function.signature of Function('load_nav_spec', 94, 114)>",
+            "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."
           }
         }
       }

mcp_docs/modules/docforge.nav.mkdocs.json

@@ -2,7 +2,7 @@
   "module": "docforge.nav.mkdocs",
   "content": {
     "path": "docforge.nav.mkdocs",
-    "docstring": "MkDocs navigation emitter.\n\nThis module provides the ``MkDocsNavEmitter`` class, which converts a\n``ResolvedNav`` instance into the navigation structure required by the\nMkDocs ``nav`` configuration.",
+    "docstring": "This module provides the MkDocsNavEmitter, which converts a ResolvedNav instance\ninto the specific YAML-ready list structure expected by the MkDocs 'nav'\nconfiguration.",
     "objects": {
       "Path": {
         "name": "Path",
@@ -37,7 +37,7 @@
         "kind": "class",
         "path": "docforge.nav.mkdocs.ResolvedNav",
         "signature": "<bound method Alias.signature of Alias('ResolvedNav', 'docforge.nav.resolver.ResolvedNav')>",
-        "docstring": "Resolved navigation structure.\n\nA ``ResolvedNav`` represents navigation data after glob patterns have been\nexpanded and paths validated against the filesystem.\n\nAttributes:\n    home: Relative path to the documentation home page.\n    groups: Mapping of navigation group titles to lists of resolved\n        documentation file paths.",
+        "docstring": "Represents a navigation structure where all patterns and paths have been\nresolved against the actual filesystem contents.\n\nAttributes:\n    home: Resolved relative path to the home page.\n    groups: Mapping of group titles to lists of absolute or relative Path objects.",
         "members": {
           "home": {
             "name": "home",
@@ -58,7 +58,7 @@
             "kind": "function",
             "path": "docforge.nav.mkdocs.ResolvedNav.all_files",
             "signature": "<bound method Alias.signature of Alias('all_files', 'docforge.nav.resolver.ResolvedNav.all_files')>",
-            "docstring": "Iterate over all files referenced by the navigation structure.\n\nReturns:\n    An iterable of ``Path`` objects representing documentation files.\n\nRaises:\n    RuntimeError: If the home page is defined but the documentation\n        root is not available for resolution."
+            "docstring": "Get an iterable of all resolved files in the navigation structure.\n\nReturns:\n    An iterable of Path objects."
           }
         }
       },
@@ -66,15 +66,15 @@
         "name": "MkDocsNavEmitter",
         "kind": "class",
         "path": "docforge.nav.mkdocs.MkDocsNavEmitter",
-        "signature": "<bound method Class.signature of Class('MkDocsNavEmitter', 15, 81)>",
-        "docstring": "Emit MkDocs navigation structures from resolved navigation data.\n\nThe emitter transforms a ``ResolvedNav`` object into the YAML-compatible\nlist structure expected by the MkDocs ``nav`` configuration field.",
+        "signature": "<bound method Class.signature of Class('MkDocsNavEmitter', 13, 72)>",
+        "docstring": "Emitter responsible for transforming a ResolvedNav into an MkDocs-compatible\nnavigation structure.",
         "members": {
           "emit": {
             "name": "emit",
             "kind": "function",
             "path": "docforge.nav.mkdocs.MkDocsNavEmitter.emit",
-            "signature": "<bound method Function.signature of Function('emit', 23, 51)>",
-            "docstring": "Generate a navigation structure for ``mkdocs.yml``.\n\nArgs:\n    nav: Resolved navigation data describing documentation groups\n        and their associated Markdown files.\n\nReturns:\n    A list of dictionaries representing the MkDocs navigation layout.\n    Each dictionary maps a navigation label to a page or a list of\n    pages."
+            "signature": "<bound method Function.signature of Function('emit', 19, 44)>",
+            "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."
           }
         }
       }

mcp_docs/modules/docforge.nav.resolver.json

@@ -2,7 +2,7 @@
   "module": "docforge.nav.resolver",
   "content": {
     "path": "docforge.nav.resolver",
-    "docstring": "Navigation resolution utilities.\n\nThis module resolves a ``NavSpec`` against the filesystem by expanding glob\npatterns and validating that referenced documentation files exist.",
+    "docstring": "This module contains the logic for resolving a NavSpec against the physical\nfilesystem. It expands globs and validates that all referenced documents\nactually exist on disk.",
     "objects": {
       "Path": {
         "name": "Path",
@@ -44,7 +44,7 @@
         "kind": "class",
         "path": "docforge.nav.resolver.NavSpec",
         "signature": "<bound method Alias.signature of Alias('NavSpec', 'docforge.nav.spec.NavSpec')>",
-        "docstring": "Parsed representation of a navigation specification.\n\nA ``NavSpec`` describes the intended documentation navigation layout before\nit is resolved against the filesystem.\n\nAttributes:\n    home: Relative path to the documentation home page (for example\n        ``index.md``).\n    groups: Mapping of navigation group titles to lists of file patterns\n        or glob expressions.",
+        "docstring": "Parsed representation of the docforge navigation specification file.\n\nAttributes:\n    home: Path to the home document (e.g., 'index.md').\n    groups: Mapping of group titles to lists of path patterns/globs.",
         "members": {
           "home": {
             "name": "home",
@@ -65,14 +65,14 @@
             "kind": "function",
             "path": "docforge.nav.resolver.NavSpec.load",
             "signature": "<bound method Alias.signature of Alias('load', 'docforge.nav.spec.NavSpec.load')>",
-            "docstring": "Load a navigation specification from a YAML file.\n\nArgs:\n    path: Filesystem path to the navigation specification file.\n\nReturns:\n    A ``NavSpec`` instance representing the parsed configuration.\n\nRaises:\n    FileNotFoundError: If the specified file does not exist.\n    ValueError: If the file contents are not a valid navigation\n        specification."
+            "docstring": "Load a NavSpec from a YAML file.\n\nArgs:\n    path: The filesystem path to the YAML file.\n\nReturns:\n    A NavSpec instance.\n\nRaises:\n    FileNotFoundError: If the path does not exist.\n    ValueError: If the file content is not a valid NavSpec mapping."
           },
           "all_patterns": {
             "name": "all_patterns",
             "kind": "function",
             "path": "docforge.nav.resolver.NavSpec.all_patterns",
             "signature": "<bound method Alias.signature of Alias('all_patterns', 'docforge.nav.spec.NavSpec.all_patterns')>",
-            "docstring": "Return all path patterns referenced by the specification.\n\nReturns:\n    A list containing the home document (if defined) and all\n    group pattern entries."
+            "docstring": "Get all path patterns referenced in the specification.\n\nReturns:\n    A list of all patterns (home plus all groups)."
           }
         }
       },
@@ -80,8 +80,8 @@
         "name": "ResolvedNav",
         "kind": "class",
         "path": "docforge.nav.resolver.ResolvedNav",
-        "signature": "<bound method Class.signature of Class('ResolvedNav', 16, 65)>",
-        "docstring": "Resolved navigation structure.\n\nA ``ResolvedNav`` represents navigation data after glob patterns have been\nexpanded and paths validated against the filesystem.\n\nAttributes:\n    home: Relative path to the documentation home page.\n    groups: Mapping of navigation group titles to lists of resolved\n        documentation file paths.",
+        "signature": "<bound method Class.signature of Class('ResolvedNav', 15, 56)>",
+        "docstring": "Represents a navigation structure where all patterns and paths have been\nresolved against the actual filesystem contents.\n\nAttributes:\n    home: Resolved relative path to the home page.\n    groups: Mapping of group titles to lists of absolute or relative Path objects.",
         "members": {
           "home": {
             "name": "home",
@@ -101,8 +101,8 @@
             "name": "all_files",
             "kind": "function",
             "path": "docforge.nav.resolver.ResolvedNav.all_files",
-            "signature": "<bound method Function.signature of Function('all_files', 47, 65)>",
-            "docstring": "Iterate over all files referenced by the navigation structure.\n\nReturns:\n    An iterable of ``Path`` objects representing documentation files.\n\nRaises:\n    RuntimeError: If the home page is defined but the documentation\n        root is not available for resolution."
+            "signature": "<bound method Function.signature of Function('all_files', 43, 56)>",
+            "docstring": "Get an iterable of all resolved files in the navigation structure.\n\nReturns:\n    An iterable of Path objects."
           }
         }
       },
@@ -110,8 +110,8 @@
         "name": "resolve_nav",
         "kind": "function",
         "path": "docforge.nav.resolver.resolve_nav",
-        "signature": "<bound method Function.signature of Function('resolve_nav', 68, 136)>",
-        "docstring": "Resolve a navigation specification against the filesystem.\n\nThe function expands glob patterns defined in a ``NavSpec`` and verifies\nthat referenced documentation files exist within the documentation root.\n\nArgs:\n    spec: Navigation specification describing documentation layout.\n    docs_root: Root directory containing documentation Markdown files.\n\nReturns:\n    A ``ResolvedNav`` instance containing validated navigation paths.\n\nRaises:\n    FileNotFoundError: If the documentation root does not exist or a\n        navigation pattern does not match any files."
+        "signature": "<bound method Function.signature of Function('resolve_nav', 59, 124)>",
+        "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."
       },
       "Optional": {
         "name": "Optional",

mcp_docs/modules/docforge.nav.spec.json

@@ -2,7 +2,7 @@
   "module": "docforge.nav.spec",
   "content": {
     "path": "docforge.nav.spec",
-    "docstring": "Navigation specification model.\n\nThis module defines the ``NavSpec`` class, which represents the navigation\nstructure defined by the user in the doc-forge navigation specification\n(typically ``docforge.nav.yml``).",
+    "docstring": "This module defines the NavSpec class, which represents the user's intent for\ndocumentation navigation as defined in a YAML specification (usually\ndocforge.nav.yml).",
     "objects": {
       "Path": {
         "name": "Path",
@@ -43,8 +43,8 @@
         "name": "NavSpec",
         "kind": "class",
         "path": "docforge.nav.spec.NavSpec",
-        "signature": "<bound method Class.signature of Class('NavSpec', 15, 104)>",
-        "docstring": "Parsed representation of a navigation specification.\n\nA ``NavSpec`` describes the intended documentation navigation layout before\nit is resolved against the filesystem.\n\nAttributes:\n    home: Relative path to the documentation home page (for example\n        ``index.md``).\n    groups: Mapping of navigation group titles to lists of file patterns\n        or glob expressions.",
+        "signature": "<bound method Class.signature of Class('NavSpec', 13, 91)>",
+        "docstring": "Parsed representation of the docforge navigation specification file.\n\nAttributes:\n    home: Path to the home document (e.g., 'index.md').\n    groups: Mapping of group titles to lists of path patterns/globs.",
         "members": {
           "home": {
             "name": "home",
@@ -64,15 +64,15 @@
             "name": "load",
             "kind": "function",
             "path": "docforge.nav.spec.NavSpec.load",
-            "signature": "<bound method Function.signature of Function('load', 45, 86)>",
-            "docstring": "Load a navigation specification from a YAML file.\n\nArgs:\n    path: Filesystem path to the navigation specification file.\n\nReturns:\n    A ``NavSpec`` instance representing the parsed configuration.\n\nRaises:\n    FileNotFoundError: If the specified file does not exist.\n    ValueError: If the file contents are not a valid navigation\n        specification."
+            "signature": "<bound method Function.signature of Function('load', 37, 77)>",
+            "docstring": "Load a NavSpec from a YAML file.\n\nArgs:\n    path: The filesystem path to the YAML file.\n\nReturns:\n    A NavSpec instance.\n\nRaises:\n    FileNotFoundError: If the path does not exist.\n    ValueError: If the file content is not a valid NavSpec mapping."
           },
           "all_patterns": {
             "name": "all_patterns",
             "kind": "function",
             "path": "docforge.nav.spec.NavSpec.all_patterns",
-            "signature": "<bound method Function.signature of Function('all_patterns', 88, 104)>",
-            "docstring": "Return all path patterns referenced by the specification.\n\nReturns:\n    A list containing the home document (if defined) and all\n    group pattern entries."
+            "signature": "<bound method Function.signature of Function('all_patterns', 79, 91)>",
+            "docstring": "Get all path patterns referenced in the specification.\n\nReturns:\n    A list of all patterns (home plus all groups)."
           }
         }
       },
@@ -80,8 +80,8 @@
         "name": "load_nav_spec",
         "kind": "function",
         "path": "docforge.nav.spec.load_nav_spec",
-        "signature": "<bound method Function.signature of Function('load_nav_spec', 107, 135)>",
-        "docstring": "Load a navigation specification file.\n\nThis helper function reads a YAML navigation file and constructs a\ncorresponding ``NavSpec`` instance.\n\nArgs:\n    path: Path to the navigation specification file.\n\nReturns:\n    A ``NavSpec`` instance representing the parsed specification.\n\nRaises:\n    FileNotFoundError: If the specification file does not exist.\n    ValueError: If the YAML structure is invalid."
+        "signature": "<bound method Function.signature of Function('load_nav_spec', 94, 114)>",
+        "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."
       }
     }
   }

mcp_docs/modules/docforge.renderers.base.json

@@ -2,7 +2,7 @@
   "module": "docforge.renderers.base",
   "content": {
     "path": "docforge.renderers.base",
-    "docstring": "Renderer base interfaces and configuration models.\n\nThis module defines the base protocol and configuration container used by\ndoc-forge renderers. Concrete renderer implementations should implement the\n``DocRenderer`` protocol.",
+    "docstring": "This module defines the base interfaces and configuration containers for\ndoc-forge renderers. All renderer implementations should adhere to the\nDocRenderer protocol.",
     "objects": {
       "Path": {
         "name": "Path",
@@ -23,7 +23,7 @@
         "kind": "class",
         "path": "docforge.renderers.base.Project",
         "signature": "<bound method Alias.signature of Alias('Project', 'docforge.models.Project')>",
-        "docstring": "Representation of a documentation project.\n\nA ``Project`` serves as the root container for all modules discovered during\nintrospection. Each module is stored by its dotted import path.\n\nAttributes:\n    name: Name of the project.\n    modules: Mapping of module paths to ``Module`` instances.",
+        "docstring": "Represents a documentation project, serving as a container for modules.\n\nAttributes:\n    name: Name of the project.\n    modules: Dictionary mapping module paths to Module instances.",
         "members": {
           "name": {
             "name": "name",
@@ -44,28 +44,28 @@
             "kind": "function",
             "path": "docforge.renderers.base.Project.add_module",
             "signature": "<bound method Alias.signature of Alias('add_module', 'docforge.models.project.Project.add_module')>",
-            "docstring": "Register a module in the project.\n\nArgs:\n    module: Module instance to add to the project."
+            "docstring": "Add a module to the project.\n\nArgs:\n    module: The module to add."
           },
           "get_module": {
             "name": "get_module",
             "kind": "function",
             "path": "docforge.renderers.base.Project.get_module",
             "signature": "<bound method Alias.signature of Alias('get_module', 'docforge.models.project.Project.get_module')>",
-            "docstring": "Retrieve a module by its dotted path.\n\nArgs:\n    path: Fully qualified dotted module path (for example ``pkg.module``).\n\nReturns:\n    The corresponding ``Module`` instance.\n\nRaises:\n    KeyError: If the module does not exist in the project."
+            "docstring": "Retrieve a module by its dotted path.\n\nArgs:\n    path: The dotted path of the module (e.g., 'pkg.mod').\n\nReturns:\n    The requested Module."
           },
           "get_all_modules": {
             "name": "get_all_modules",
             "kind": "function",
             "path": "docforge.renderers.base.Project.get_all_modules",
             "signature": "<bound method Alias.signature of Alias('get_all_modules', 'docforge.models.project.Project.get_all_modules')>",
-            "docstring": "Return all modules contained in the project.\n\nReturns:\n    An iterable of ``Module`` instances."
+            "docstring": "Get all modules in the project.\n\nReturns:\n    An iterable of Module objects."
           },
           "get_module_list": {
             "name": "get_module_list",
             "kind": "function",
             "path": "docforge.renderers.base.Project.get_module_list",
             "signature": "<bound method Alias.signature of Alias('get_module_list', 'docforge.models.project.Project.get_module_list')>",
-            "docstring": "Return the list of module import paths.\n\nReturns:\n    A list containing the dotted paths of all modules in the project."
+            "docstring": "Get the list of all module dotted paths.\n\nReturns:\n    A list of module paths."
           }
         }
       },
@@ -73,8 +73,8 @@
         "name": "RendererConfig",
         "kind": "class",
         "path": "docforge.renderers.base.RendererConfig",
-        "signature": "<bound method Class.signature of Class('RendererConfig', 15, 36)>",
-        "docstring": "Configuration container for documentation renderers.\n\nA ``RendererConfig`` instance groups together the project model and the\noutput directory used during rendering.\n\nAttributes:\n    out_dir: Directory where generated documentation files will be written.\n    project: Documentation project model to be rendered.",
+        "signature": "<bound method Class.signature of Class('RendererConfig', 13, 24)>",
+        "docstring": "Configuration container for documentation renderers.\n\nArgs:\n    out_dir: The directory where documentation files should be written.\n    project: The introspected project models to be rendered.",
         "members": {
           "out_dir": {
             "name": "out_dir",
@@ -96,8 +96,8 @@
         "name": "DocRenderer",
         "kind": "class",
         "path": "docforge.renderers.base.DocRenderer",
-        "signature": "<bound method Class.signature of Class('DocRenderer', 39, 62)>",
-        "docstring": "Protocol defining the interface for documentation renderers.\n\nImplementations of this protocol are responsible for transforming a\n``Project`` model into renderer-specific documentation sources.",
+        "signature": "<bound method Class.signature of Class('DocRenderer', 27, 46)>",
+        "docstring": "Protocol defining the interface for documentation renderers.",
         "members": {
           "name": {
             "name": "name",
@@ -110,8 +110,8 @@
             "name": "generate_sources",
             "kind": "function",
             "path": "docforge.renderers.base.DocRenderer.generate_sources",
-            "signature": "<bound method Function.signature of Function('generate_sources', 49, 62)>",
-            "docstring": "Generate renderer-specific documentation sources.\n\nArgs:\n    project: Project model containing modules and documentation objects.\n    out_dir: Directory where generated documentation sources\n        should be written."
+            "signature": "<bound method Function.signature of Function('generate_sources', 34, 46)>",
+            "docstring": "Generate renderer-specific source files for the given project.\n\nArgs:\n    project: The project models containing modules and objects.\n    out_dir: Target directory for the generated files."
           }
         }
       }

mcp_docs/modules/docforge.renderers.json

@@ -2,14 +2,14 @@
   "module": "docforge.renderers",
   "content": {
     "path": "docforge.renderers",
-    "docstring": "Renderers layer for doc-forge.\n\nThe ``docforge.renderers`` package transforms the internal documentation\nmodels into files formatted for specific documentation systems.\n\n---\n\nOverview\n--------\n\nRenderers consume the doc-forge project model and generate output suitable\nfor documentation tools or machine interfaces.\n\nCurrent implementations:\n\n- **MkDocsRenderer** – Produces Markdown files compatible with MkDocs and\n  the ``mkdocstrings`` plugin. It automatically handles package hierarchy\n  and generates ``index.md`` files for packages.\n- **MCPRenderer** – Emits structured JSON resources designed for consumption\n  by Model Context Protocol (MCP) clients.\n\n---\n\nExtending\n---------\n\nNew renderers can be added by implementing the ``DocRenderer`` protocol\ndefined in ``docforge.renderers.base``.\n\n---",
+    "docstring": "# Renderers Layer\n\nThe `docforge.renderers` package handles the transformation of the internal\ndocumentation models into physical files formatted for specific documentation\nengines.\n\n## Current Implementations\n\n- **MkDocsRenderer**: Generates Markdown files utilizing the `mkdocstrings`\n  syntax. It automatically handles package/module hierarchy and generates\n  `index.md` files for packages.\n\n## Extending\n\nTo add a new renderer, implement the `DocRenderer` protocol defined in\n`docforge.renderers.base`.",
     "objects": {
       "MkDocsRenderer": {
         "name": "MkDocsRenderer",
         "kind": "class",
         "path": "docforge.renderers.MkDocsRenderer",
         "signature": "<bound method Alias.signature of Alias('MkDocsRenderer', 'docforge.renderers.mkdocs_renderer.MkDocsRenderer')>",
-        "docstring": "Renderer that produces Markdown documentation for MkDocs.\n\nGenerated pages use mkdocstrings directives to reference Python modules,\nallowing MkDocs to render API documentation dynamically.",
+        "docstring": "Renderer that generates Markdown source files formatted for the MkDocs\n'mkdocstrings' plugin.",
         "members": {
           "name": {
             "name": "name",
@@ -23,14 +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": "Generate Markdown documentation files for a project.\n\nThis method renders a documentation structure from the provided\nproject model and writes the resulting Markdown files to the\nspecified output directory.\n\nArgs:\n    project: Project model containing modules to document.\n    out_dir: Directory where generated Markdown files will be written.\n    module_is_source: If True, treat the specified module as the\n        documentation root rather than nesting it inside a folder."
-          },
-          "generate_readme": {
-            "name": "generate_readme",
-            "kind": "function",
-            "path": "docforge.renderers.MkDocsRenderer.generate_readme",
-            "signature": "<bound method Alias.signature of Alias('generate_readme', 'docforge.renderers.mkdocs_renderer.MkDocsRenderer.generate_readme')>",
-            "docstring": "Generate a ``README.md`` file from the root module docstring.\n\nBehavior:\n\n- If ``module_is_source`` is True, ``README.md`` is written to the\n  project root directory.\n- If False, README generation is currently not implemented.\n\nArgs:\n    project: Project model containing documentation metadata.\n    docs_dir: Directory containing generated documentation sources.\n    module_is_source: Whether the module is treated as the project\n        source root."
+            "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."
           }
         }
       },
@@ -39,7 +32,7 @@
         "kind": "class",
         "path": "docforge.renderers.MCPRenderer",
         "signature": "<bound method Alias.signature of Alias('MCPRenderer', 'docforge.renderers.mcp_renderer.MCPRenderer')>",
-        "docstring": "Renderer that generates MCP-compatible documentation resources.\n\nThis renderer converts doc-forge project models into structured JSON\nresources suitable for consumption by systems implementing the Model\nContext Protocol (MCP).",
+        "docstring": "Renderer that emits MCP-native JSON resources from docforge models.",
         "members": {
           "name": {
             "name": "name",
@@ -53,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 documentation resources for a project.\n\nThe renderer serializes each module into a JSON resource and produces\nsupporting metadata files such as ``nav.json`` and ``index.json``.\n\nArgs:\n    project: Documentation project model to render.\n    out_dir: Directory where MCP resources will be written."
+            "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."
           }
         }
       },
@@ -62,7 +55,7 @@
         "kind": "module",
         "path": "docforge.renderers.base",
         "signature": null,
-        "docstring": "Renderer base interfaces and configuration models.\n\nThis module defines the base protocol and configuration container used by\ndoc-forge renderers. Concrete renderer implementations should implement the\n``DocRenderer`` protocol.",
+        "docstring": "This module defines the base interfaces and configuration containers for\ndoc-forge renderers. All renderer implementations should adhere to the\nDocRenderer protocol.",
         "members": {
           "Path": {
             "name": "Path",
@@ -83,7 +76,7 @@
             "kind": "class",
             "path": "docforge.renderers.base.Project",
             "signature": "<bound method Alias.signature of Alias('Project', 'docforge.models.Project')>",
-            "docstring": "Representation of a documentation project.\n\nA ``Project`` serves as the root container for all modules discovered during\nintrospection. Each module is stored by its dotted import path.\n\nAttributes:\n    name: Name of the project.\n    modules: Mapping of module paths to ``Module`` instances.",
+            "docstring": "Represents a documentation project, serving as a container for modules.\n\nAttributes:\n    name: Name of the project.\n    modules: Dictionary mapping module paths to Module instances.",
             "members": {
               "name": {
                 "name": "name",
@@ -104,28 +97,28 @@
                 "kind": "function",
                 "path": "docforge.renderers.base.Project.add_module",
                 "signature": "<bound method Alias.signature of Alias('add_module', 'docforge.models.project.Project.add_module')>",
-                "docstring": "Register a module in the project.\n\nArgs:\n    module: Module instance to add to the project."
+                "docstring": "Add a module to the project.\n\nArgs:\n    module: The module to add."
               },
               "get_module": {
                 "name": "get_module",
                 "kind": "function",
                 "path": "docforge.renderers.base.Project.get_module",
                 "signature": "<bound method Alias.signature of Alias('get_module', 'docforge.models.project.Project.get_module')>",
-                "docstring": "Retrieve a module by its dotted path.\n\nArgs:\n    path: Fully qualified dotted module path (for example ``pkg.module``).\n\nReturns:\n    The corresponding ``Module`` instance.\n\nRaises:\n    KeyError: If the module does not exist in the project."
+                "docstring": "Retrieve a module by its dotted path.\n\nArgs:\n    path: The dotted path of the module (e.g., 'pkg.mod').\n\nReturns:\n    The requested Module."
               },
               "get_all_modules": {
                 "name": "get_all_modules",
                 "kind": "function",
                 "path": "docforge.renderers.base.Project.get_all_modules",
                 "signature": "<bound method Alias.signature of Alias('get_all_modules', 'docforge.models.project.Project.get_all_modules')>",
-                "docstring": "Return all modules contained in the project.\n\nReturns:\n    An iterable of ``Module`` instances."
+                "docstring": "Get all modules in the project.\n\nReturns:\n    An iterable of Module objects."
               },
               "get_module_list": {
                 "name": "get_module_list",
                 "kind": "function",
                 "path": "docforge.renderers.base.Project.get_module_list",
                 "signature": "<bound method Alias.signature of Alias('get_module_list', 'docforge.models.project.Project.get_module_list')>",
-                "docstring": "Return the list of module import paths.\n\nReturns:\n    A list containing the dotted paths of all modules in the project."
+                "docstring": "Get the list of all module dotted paths.\n\nReturns:\n    A list of module paths."
               }
             }
           },
@@ -133,8 +126,8 @@
             "name": "RendererConfig",
             "kind": "class",
             "path": "docforge.renderers.base.RendererConfig",
-            "signature": "<bound method Class.signature of Class('RendererConfig', 15, 36)>",
-            "docstring": "Configuration container for documentation renderers.\n\nA ``RendererConfig`` instance groups together the project model and the\noutput directory used during rendering.\n\nAttributes:\n    out_dir: Directory where generated documentation files will be written.\n    project: Documentation project model to be rendered.",
+            "signature": "<bound method Class.signature of Class('RendererConfig', 13, 24)>",
+            "docstring": "Configuration container for documentation renderers.\n\nArgs:\n    out_dir: The directory where documentation files should be written.\n    project: The introspected project models to be rendered.",
             "members": {
               "out_dir": {
                 "name": "out_dir",
@@ -156,8 +149,8 @@
             "name": "DocRenderer",
             "kind": "class",
             "path": "docforge.renderers.base.DocRenderer",
-            "signature": "<bound method Class.signature of Class('DocRenderer', 39, 62)>",
-            "docstring": "Protocol defining the interface for documentation renderers.\n\nImplementations of this protocol are responsible for transforming a\n``Project`` model into renderer-specific documentation sources.",
+            "signature": "<bound method Class.signature of Class('DocRenderer', 27, 46)>",
+            "docstring": "Protocol defining the interface for documentation renderers.",
             "members": {
               "name": {
                 "name": "name",
@@ -170,8 +163,8 @@
                 "name": "generate_sources",
                 "kind": "function",
                 "path": "docforge.renderers.base.DocRenderer.generate_sources",
-                "signature": "<bound method Function.signature of Function('generate_sources', 49, 62)>",
-                "docstring": "Generate renderer-specific documentation sources.\n\nArgs:\n    project: Project model containing modules and documentation objects.\n    out_dir: Directory where generated documentation sources\n        should be written."
+                "signature": "<bound method Function.signature of Function('generate_sources', 34, 46)>",
+                "docstring": "Generate renderer-specific source files for the given project.\n\nArgs:\n    project: The project models containing modules and objects.\n    out_dir: Target directory for the generated files."
               }
             }
           }
@@ -217,7 +210,7 @@
             "kind": "class",
             "path": "docforge.renderers.mcp_renderer.Project",
             "signature": "<bound method Alias.signature of Alias('Project', 'docforge.models.Project')>",
-            "docstring": "Representation of a documentation project.\n\nA ``Project`` serves as the root container for all modules discovered during\nintrospection. Each module is stored by its dotted import path.\n\nAttributes:\n    name: Name of the project.\n    modules: Mapping of module paths to ``Module`` instances.",
+            "docstring": "Represents a documentation project, serving as a container for modules.\n\nAttributes:\n    name: Name of the project.\n    modules: Dictionary mapping module paths to Module instances.",
             "members": {
               "name": {
                 "name": "name",
@@ -238,28 +231,28 @@
                 "kind": "function",
                 "path": "docforge.renderers.mcp_renderer.Project.add_module",
                 "signature": "<bound method Alias.signature of Alias('add_module', 'docforge.models.project.Project.add_module')>",
-                "docstring": "Register a module in the project.\n\nArgs:\n    module: Module instance to add to the project."
+                "docstring": "Add a module to the project.\n\nArgs:\n    module: The module to add."
               },
               "get_module": {
                 "name": "get_module",
                 "kind": "function",
                 "path": "docforge.renderers.mcp_renderer.Project.get_module",
                 "signature": "<bound method Alias.signature of Alias('get_module', 'docforge.models.project.Project.get_module')>",
-                "docstring": "Retrieve a module by its dotted path.\n\nArgs:\n    path: Fully qualified dotted module path (for example ``pkg.module``).\n\nReturns:\n    The corresponding ``Module`` instance.\n\nRaises:\n    KeyError: If the module does not exist in the project."
+                "docstring": "Retrieve a module by its dotted path.\n\nArgs:\n    path: The dotted path of the module (e.g., 'pkg.mod').\n\nReturns:\n    The requested Module."
               },
               "get_all_modules": {
                 "name": "get_all_modules",
                 "kind": "function",
                 "path": "docforge.renderers.mcp_renderer.Project.get_all_modules",
                 "signature": "<bound method Alias.signature of Alias('get_all_modules', 'docforge.models.project.Project.get_all_modules')>",
-                "docstring": "Return all modules contained in the project.\n\nReturns:\n    An iterable of ``Module`` instances."
+                "docstring": "Get all modules in the project.\n\nReturns:\n    An iterable of Module objects."
               },
               "get_module_list": {
                 "name": "get_module_list",
                 "kind": "function",
                 "path": "docforge.renderers.mcp_renderer.Project.get_module_list",
                 "signature": "<bound method Alias.signature of Alias('get_module_list', 'docforge.models.project.Project.get_module_list')>",
-                "docstring": "Return the list of module import paths.\n\nReturns:\n    A list containing the dotted paths of all modules in the project."
+                "docstring": "Get the list of all module dotted paths.\n\nReturns:\n    A list of module paths."
               }
             }
           },
@@ -268,7 +261,7 @@
             "kind": "class",
             "path": "docforge.renderers.mcp_renderer.Module",
             "signature": "<bound method Alias.signature of Alias('Module', 'docforge.models.Module')>",
-            "docstring": "Representation of a documented Python module or package.\n\nA ``Module`` stores metadata about the module itself and maintains a\ncollection of top-level documentation objects discovered during\nintrospection.\n\nAttributes:\n    path: Dotted import path of the module.\n    docstring: Module-level documentation string, if present.\n    members: Mapping of object names to their corresponding\n        ``DocObject`` representations.",
+            "docstring": "Represents a documented Python module or package.\n\nAttributes:\n    path: Dotted import path of the module.\n    docstring: Module-level docstring content.\n    members: Dictionary mapping object names to their DocObject representations.",
             "members": {
               "path": {
                 "name": "path",
@@ -296,21 +289,21 @@
                 "kind": "function",
                 "path": "docforge.renderers.mcp_renderer.Module.add_object",
                 "signature": "<bound method Alias.signature of Alias('add_object', 'docforge.models.module.Module.add_object')>",
-                "docstring": "Add a documented object to the module.\n\nArgs:\n    obj: Documentation object to register as a top-level\n        member of the module."
+                "docstring": "Add a documented object to the module.\n\nArgs:\n    obj: The object to add."
               },
               "get_object": {
                 "name": "get_object",
                 "kind": "function",
                 "path": "docforge.renderers.mcp_renderer.Module.get_object",
                 "signature": "<bound method Alias.signature of Alias('get_object', 'docforge.models.module.Module.get_object')>",
-                "docstring": "Retrieve a documented object by name.\n\nArgs:\n    name: Name of the object to retrieve.\n\nReturns:\n    The corresponding ``DocObject`` instance.\n\nRaises:\n    KeyError: If no object with the given name exists."
+                "docstring": "Retrieve a member object by name.\n\nArgs:\n    name: The name of the object.\n\nReturns:\n    The requested DocObject."
               },
               "get_all_objects": {
                 "name": "get_all_objects",
                 "kind": "function",
                 "path": "docforge.renderers.mcp_renderer.Module.get_all_objects",
                 "signature": "<bound method Alias.signature of Alias('get_all_objects', 'docforge.models.module.Module.get_all_objects')>",
-                "docstring": "Return all top-level documentation objects in the module.\n\nReturns:\n    An iterable of ``DocObject`` instances representing the\n    module's public members."
+                "docstring": "Get all top-level objects in the module.\n\nReturns:\n    An iterable of DocObject instances."
               }
             }
           },
@@ -319,7 +312,7 @@
             "kind": "class",
             "path": "docforge.renderers.mcp_renderer.DocObject",
             "signature": "<bound method Alias.signature of Alias('DocObject', 'docforge.models.DocObject')>",
-            "docstring": "Representation of a documented Python object.\n\nA ``DocObject`` models a single Python entity discovered during\nintrospection. Objects may contain nested members, allowing the structure\nof modules, classes, and other containers to be represented recursively.\n\nAttributes:\n    name: Local name of the object.\n    kind: Type of object (for example ``class``, ``function``,\n        ``method``, or ``attribute``).\n    path: Fully qualified dotted path to the object.\n    signature: Callable signature if the object represents a callable.\n    docstring: Raw docstring text extracted from the source code.\n    members: Mapping of member names to child ``DocObject`` instances.",
+            "docstring": "Represents a documented Python object (class, function, method, etc.).\n\nAttributes:\n    name: Local name of the object.\n    kind: Type of object (e.g., 'class', 'function', 'attribute').\n    path: Full dotted import path to the object.\n    signature: Callable signature, if applicable.\n    docstring: Raw docstring content extracted from the source.\n    members: Dictionary mapping member names to their DocObject representations.",
             "members": {
               "name": {
                 "name": "name",
@@ -368,21 +361,21 @@
                 "kind": "function",
                 "path": "docforge.renderers.mcp_renderer.DocObject.add_member",
                 "signature": "<bound method Alias.signature of Alias('add_member', 'docforge.models.object.DocObject.add_member')>",
-                "docstring": "Add a child documentation object.\n\nThis is typically used when attaching methods to classes or\nnested objects to their parent containers.\n\nArgs:\n    obj: Documentation object to add as a member."
+                "docstring": "Add a child member to this object (e.g., a method to a class).\n\nArgs:\n    obj: The child DocObject to add."
               },
               "get_member": {
                 "name": "get_member",
                 "kind": "function",
                 "path": "docforge.renderers.mcp_renderer.DocObject.get_member",
                 "signature": "<bound method Alias.signature of Alias('get_member', 'docforge.models.object.DocObject.get_member')>",
-                "docstring": "Retrieve a member object by name.\n\nArgs:\n    name: Name of the member to retrieve.\n\nReturns:\n    The corresponding ``DocObject`` instance.\n\nRaises:\n    KeyError: If the member does not exist."
+                "docstring": "Retrieve a child member by name.\n\nArgs:\n    name: The name of the member.\n\nReturns:\n    The requested DocObject."
               },
               "get_all_members": {
                 "name": "get_all_members",
                 "kind": "function",
                 "path": "docforge.renderers.mcp_renderer.DocObject.get_all_members",
                 "signature": "<bound method Alias.signature of Alias('get_all_members', 'docforge.models.object.DocObject.get_all_members')>",
-                "docstring": "Return all child members of the object.\n\nReturns:\n    An iterable of ``DocObject`` instances representing nested members."
+                "docstring": "Get all members of this object.\n\nReturns:\n    An iterable of child DocObject instances."
               }
             }
           },
@@ -390,8 +383,8 @@
             "name": "MCPRenderer",
             "kind": "class",
             "path": "docforge.renderers.mcp_renderer.MCPRenderer",
-            "signature": "<bound method Class.signature of Class('MCPRenderer', 8, 138)>",
-            "docstring": "Renderer that generates MCP-compatible documentation resources.\n\nThis renderer converts doc-forge project models into structured JSON\nresources suitable for consumption by systems implementing the Model\nContext Protocol (MCP).",
+            "signature": "<bound method Class.signature of Class('MCPRenderer', 8, 122)>",
+            "docstring": "Renderer that emits MCP-native JSON resources from docforge models.",
             "members": {
               "name": {
                 "name": "name",
@@ -404,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', 19, 60)>",
-                "docstring": "Generate MCP documentation resources for a project.\n\nThe renderer serializes each module into a JSON resource and produces\nsupporting metadata files such as ``nav.json`` and ``index.json``.\n\nArgs:\n    project: Documentation project model to render.\n    out_dir: Directory where MCP resources will be written."
+                "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."
               }
             }
           }
@@ -416,7 +409,7 @@
         "kind": "module",
         "path": "docforge.renderers.mkdocs_renderer",
         "signature": null,
-        "docstring": "MkDocs renderer implementation.\n\nThis module defines the ``MkDocsRenderer`` class, which generates Markdown\ndocumentation sources compatible with MkDocs Material and the mkdocstrings\nplugin.\n\nThe renderer ensures a consistent documentation structure by:\n\n- Creating a root ``index.md`` if one does not exist\n- Generating package index pages automatically\n- Linking child modules within parent package pages\n- Optionally generating ``README.md`` from the root package docstring",
+        "docstring": "This module implements the MkDocsRenderer, which generates Markdown source files\ncompatible with the MkDocs 'material' theme and 'mkdocstrings' extension.",
         "members": {
           "Path": {
             "name": "Path",
@@ -430,7 +423,7 @@
             "kind": "class",
             "path": "docforge.renderers.mkdocs_renderer.Project",
             "signature": "<bound method Alias.signature of Alias('Project', 'docforge.models.Project')>",
-            "docstring": "Representation of a documentation project.\n\nA ``Project`` serves as the root container for all modules discovered during\nintrospection. Each module is stored by its dotted import path.\n\nAttributes:\n    name: Name of the project.\n    modules: Mapping of module paths to ``Module`` instances.",
+            "docstring": "Represents a documentation project, serving as a container for modules.\n\nAttributes:\n    name: Name of the project.\n    modules: Dictionary mapping module paths to Module instances.",
             "members": {
               "name": {
                 "name": "name",
@@ -451,37 +444,67 @@
                 "kind": "function",
                 "path": "docforge.renderers.mkdocs_renderer.Project.add_module",
                 "signature": "<bound method Alias.signature of Alias('add_module', 'docforge.models.project.Project.add_module')>",
-                "docstring": "Register a module in the project.\n\nArgs:\n    module: Module instance to add to the project."
+                "docstring": "Add a module to the project.\n\nArgs:\n    module: The module to add."
               },
               "get_module": {
                 "name": "get_module",
                 "kind": "function",
                 "path": "docforge.renderers.mkdocs_renderer.Project.get_module",
                 "signature": "<bound method Alias.signature of Alias('get_module', 'docforge.models.project.Project.get_module')>",
-                "docstring": "Retrieve a module by its dotted path.\n\nArgs:\n    path: Fully qualified dotted module path (for example ``pkg.module``).\n\nReturns:\n    The corresponding ``Module`` instance.\n\nRaises:\n    KeyError: If the module does not exist in the project."
+                "docstring": "Retrieve a module by its dotted path.\n\nArgs:\n    path: The dotted path of the module (e.g., 'pkg.mod').\n\nReturns:\n    The requested Module."
               },
               "get_all_modules": {
                 "name": "get_all_modules",
                 "kind": "function",
                 "path": "docforge.renderers.mkdocs_renderer.Project.get_all_modules",
                 "signature": "<bound method Alias.signature of Alias('get_all_modules', 'docforge.models.project.Project.get_all_modules')>",
-                "docstring": "Return all modules contained in the project.\n\nReturns:\n    An iterable of ``Module`` instances."
+                "docstring": "Get all modules in the project.\n\nReturns:\n    An iterable of Module objects."
               },
               "get_module_list": {
                 "name": "get_module_list",
                 "kind": "function",
                 "path": "docforge.renderers.mkdocs_renderer.Project.get_module_list",
                 "signature": "<bound method Alias.signature of Alias('get_module_list', 'docforge.models.project.Project.get_module_list')>",
-                "docstring": "Return the list of module import paths.\n\nReturns:\n    A list containing the dotted paths of all modules in the project."
+                "docstring": "Get the list of all module dotted paths.\n\nReturns:\n    A list of module paths."
               }
             }
           },
+          "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",
             "path": "docforge.renderers.mkdocs_renderer.Module",
             "signature": "<bound method Alias.signature of Alias('Module', 'docforge.models.Module')>",
-            "docstring": "Representation of a documented Python module or package.\n\nA ``Module`` stores metadata about the module itself and maintains a\ncollection of top-level documentation objects discovered during\nintrospection.\n\nAttributes:\n    path: Dotted import path of the module.\n    docstring: Module-level documentation string, if present.\n    members: Mapping of object names to their corresponding\n        ``DocObject`` representations.",
+            "docstring": "Represents a documented Python module or package.\n\nAttributes:\n    path: Dotted import path of the module.\n    docstring: Module-level docstring content.\n    members: Dictionary mapping object names to their DocObject representations.",
             "members": {
               "path": {
                 "name": "path",
@@ -509,51 +532,21 @@
                 "kind": "function",
                 "path": "docforge.renderers.mkdocs_renderer.Module.add_object",
                 "signature": "<bound method Alias.signature of Alias('add_object', 'docforge.models.module.Module.add_object')>",
-                "docstring": "Add a documented object to the module.\n\nArgs:\n    obj: Documentation object to register as a top-level\n        member of the module."
+                "docstring": "Add a documented object to the module.\n\nArgs:\n    obj: The object to add."
               },
               "get_object": {
                 "name": "get_object",
                 "kind": "function",
                 "path": "docforge.renderers.mkdocs_renderer.Module.get_object",
                 "signature": "<bound method Alias.signature of Alias('get_object', 'docforge.models.module.Module.get_object')>",
-                "docstring": "Retrieve a documented object by name.\n\nArgs:\n    name: Name of the object to retrieve.\n\nReturns:\n    The corresponding ``DocObject`` instance.\n\nRaises:\n    KeyError: If no object with the given name exists."
+                "docstring": "Retrieve a member object by name.\n\nArgs:\n    name: The name of the object.\n\nReturns:\n    The requested DocObject."
               },
               "get_all_objects": {
                 "name": "get_all_objects",
                 "kind": "function",
                 "path": "docforge.renderers.mkdocs_renderer.Module.get_all_objects",
                 "signature": "<bound method Alias.signature of Alias('get_all_objects', 'docforge.models.module.Module.get_all_objects')>",
-                "docstring": "Return all top-level documentation objects in the module.\n\nReturns:\n    An iterable of ``DocObject`` instances representing the\n    module's public members."
-              }
-            }
-          },
-          "MkDocsRenderer": {
-            "name": "MkDocsRenderer",
-            "kind": "class",
-            "path": "docforge.renderers.mkdocs_renderer.MkDocsRenderer",
-            "signature": "<bound method Class.signature of Class('MkDocsRenderer', 20, 272)>",
-            "docstring": "Renderer that produces Markdown documentation for MkDocs.\n\nGenerated pages use mkdocstrings directives to reference Python modules,\nallowing MkDocs to render API documentation dynamically.",
-            "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', 34, 71)>",
-                "docstring": "Generate Markdown documentation files for a project.\n\nThis method renders a documentation structure from the provided\nproject model and writes the resulting Markdown files to the\nspecified output directory.\n\nArgs:\n    project: Project model containing modules to document.\n    out_dir: Directory where generated Markdown files will be written.\n    module_is_source: If True, treat the specified module as the\n        documentation root rather than nesting it inside a folder."
-              },
-              "generate_readme": {
-                "name": "generate_readme",
-                "kind": "function",
-                "path": "docforge.renderers.mkdocs_renderer.MkDocsRenderer.generate_readme",
-                "signature": "<bound method Function.signature of Function('generate_readme', 73, 128)>",
-                "docstring": "Generate a ``README.md`` file from the root module docstring.\n\nBehavior:\n\n- If ``module_is_source`` is True, ``README.md`` is written to the\n  project root directory.\n- If False, README generation is currently not implemented.\n\nArgs:\n    project: Project model containing documentation metadata.\n    docs_dir: Directory containing generated documentation sources.\n    module_is_source: Whether the module is treated as the project\n        source root."
+                "docstring": "Get all top-level objects in the module.\n\nReturns:\n    An iterable of DocObject instances."
               }
             }
           }

mcp_docs/modules/docforge.renderers.mcp_renderer.json

@@ -37,7 +37,7 @@
         "kind": "class",
         "path": "docforge.renderers.mcp_renderer.Project",
         "signature": "<bound method Alias.signature of Alias('Project', 'docforge.models.Project')>",
-        "docstring": "Representation of a documentation project.\n\nA ``Project`` serves as the root container for all modules discovered during\nintrospection. Each module is stored by its dotted import path.\n\nAttributes:\n    name: Name of the project.\n    modules: Mapping of module paths to ``Module`` instances.",
+        "docstring": "Represents a documentation project, serving as a container for modules.\n\nAttributes:\n    name: Name of the project.\n    modules: Dictionary mapping module paths to Module instances.",
         "members": {
           "name": {
             "name": "name",
@@ -58,28 +58,28 @@
             "kind": "function",
             "path": "docforge.renderers.mcp_renderer.Project.add_module",
             "signature": "<bound method Alias.signature of Alias('add_module', 'docforge.models.project.Project.add_module')>",
-            "docstring": "Register a module in the project.\n\nArgs:\n    module: Module instance to add to the project."
+            "docstring": "Add a module to the project.\n\nArgs:\n    module: The module to add."
           },
           "get_module": {
             "name": "get_module",
             "kind": "function",
             "path": "docforge.renderers.mcp_renderer.Project.get_module",
             "signature": "<bound method Alias.signature of Alias('get_module', 'docforge.models.project.Project.get_module')>",
-            "docstring": "Retrieve a module by its dotted path.\n\nArgs:\n    path: Fully qualified dotted module path (for example ``pkg.module``).\n\nReturns:\n    The corresponding ``Module`` instance.\n\nRaises:\n    KeyError: If the module does not exist in the project."
+            "docstring": "Retrieve a module by its dotted path.\n\nArgs:\n    path: The dotted path of the module (e.g., 'pkg.mod').\n\nReturns:\n    The requested Module."
           },
           "get_all_modules": {
             "name": "get_all_modules",
             "kind": "function",
             "path": "docforge.renderers.mcp_renderer.Project.get_all_modules",
             "signature": "<bound method Alias.signature of Alias('get_all_modules', 'docforge.models.project.Project.get_all_modules')>",
-            "docstring": "Return all modules contained in the project.\n\nReturns:\n    An iterable of ``Module`` instances."
+            "docstring": "Get all modules in the project.\n\nReturns:\n    An iterable of Module objects."
           },
           "get_module_list": {
             "name": "get_module_list",
             "kind": "function",
             "path": "docforge.renderers.mcp_renderer.Project.get_module_list",
             "signature": "<bound method Alias.signature of Alias('get_module_list', 'docforge.models.project.Project.get_module_list')>",
-            "docstring": "Return the list of module import paths.\n\nReturns:\n    A list containing the dotted paths of all modules in the project."
+            "docstring": "Get the list of all module dotted paths.\n\nReturns:\n    A list of module paths."
           }
         }
       },
@@ -88,7 +88,7 @@
         "kind": "class",
         "path": "docforge.renderers.mcp_renderer.Module",
         "signature": "<bound method Alias.signature of Alias('Module', 'docforge.models.Module')>",
-        "docstring": "Representation of a documented Python module or package.\n\nA ``Module`` stores metadata about the module itself and maintains a\ncollection of top-level documentation objects discovered during\nintrospection.\n\nAttributes:\n    path: Dotted import path of the module.\n    docstring: Module-level documentation string, if present.\n    members: Mapping of object names to their corresponding\n        ``DocObject`` representations.",
+        "docstring": "Represents a documented Python module or package.\n\nAttributes:\n    path: Dotted import path of the module.\n    docstring: Module-level docstring content.\n    members: Dictionary mapping object names to their DocObject representations.",
         "members": {
           "path": {
             "name": "path",
@@ -116,21 +116,21 @@
             "kind": "function",
             "path": "docforge.renderers.mcp_renderer.Module.add_object",
             "signature": "<bound method Alias.signature of Alias('add_object', 'docforge.models.module.Module.add_object')>",
-            "docstring": "Add a documented object to the module.\n\nArgs:\n    obj: Documentation object to register as a top-level\n        member of the module."
+            "docstring": "Add a documented object to the module.\n\nArgs:\n    obj: The object to add."
           },
           "get_object": {
             "name": "get_object",
             "kind": "function",
             "path": "docforge.renderers.mcp_renderer.Module.get_object",
             "signature": "<bound method Alias.signature of Alias('get_object', 'docforge.models.module.Module.get_object')>",
-            "docstring": "Retrieve a documented object by name.\n\nArgs:\n    name: Name of the object to retrieve.\n\nReturns:\n    The corresponding ``DocObject`` instance.\n\nRaises:\n    KeyError: If no object with the given name exists."
+            "docstring": "Retrieve a member object by name.\n\nArgs:\n    name: The name of the object.\n\nReturns:\n    The requested DocObject."
           },
           "get_all_objects": {
             "name": "get_all_objects",
             "kind": "function",
             "path": "docforge.renderers.mcp_renderer.Module.get_all_objects",
             "signature": "<bound method Alias.signature of Alias('get_all_objects', 'docforge.models.module.Module.get_all_objects')>",
-            "docstring": "Return all top-level documentation objects in the module.\n\nReturns:\n    An iterable of ``DocObject`` instances representing the\n    module's public members."
+            "docstring": "Get all top-level objects in the module.\n\nReturns:\n    An iterable of DocObject instances."
           }
         }
       },
@@ -139,7 +139,7 @@
         "kind": "class",
         "path": "docforge.renderers.mcp_renderer.DocObject",
         "signature": "<bound method Alias.signature of Alias('DocObject', 'docforge.models.DocObject')>",
-        "docstring": "Representation of a documented Python object.\n\nA ``DocObject`` models a single Python entity discovered during\nintrospection. Objects may contain nested members, allowing the structure\nof modules, classes, and other containers to be represented recursively.\n\nAttributes:\n    name: Local name of the object.\n    kind: Type of object (for example ``class``, ``function``,\n        ``method``, or ``attribute``).\n    path: Fully qualified dotted path to the object.\n    signature: Callable signature if the object represents a callable.\n    docstring: Raw docstring text extracted from the source code.\n    members: Mapping of member names to child ``DocObject`` instances.",
+        "docstring": "Represents a documented Python object (class, function, method, etc.).\n\nAttributes:\n    name: Local name of the object.\n    kind: Type of object (e.g., 'class', 'function', 'attribute').\n    path: Full dotted import path to the object.\n    signature: Callable signature, if applicable.\n    docstring: Raw docstring content extracted from the source.\n    members: Dictionary mapping member names to their DocObject representations.",
         "members": {
           "name": {
             "name": "name",
@@ -188,21 +188,21 @@
             "kind": "function",
             "path": "docforge.renderers.mcp_renderer.DocObject.add_member",
             "signature": "<bound method Alias.signature of Alias('add_member', 'docforge.models.object.DocObject.add_member')>",
-            "docstring": "Add a child documentation object.\n\nThis is typically used when attaching methods to classes or\nnested objects to their parent containers.\n\nArgs:\n    obj: Documentation object to add as a member."
+            "docstring": "Add a child member to this object (e.g., a method to a class).\n\nArgs:\n    obj: The child DocObject to add."
           },
           "get_member": {
             "name": "get_member",
             "kind": "function",
             "path": "docforge.renderers.mcp_renderer.DocObject.get_member",
             "signature": "<bound method Alias.signature of Alias('get_member', 'docforge.models.object.DocObject.get_member')>",
-            "docstring": "Retrieve a member object by name.\n\nArgs:\n    name: Name of the member to retrieve.\n\nReturns:\n    The corresponding ``DocObject`` instance.\n\nRaises:\n    KeyError: If the member does not exist."
+            "docstring": "Retrieve a child member by name.\n\nArgs:\n    name: The name of the member.\n\nReturns:\n    The requested DocObject."
           },
           "get_all_members": {
             "name": "get_all_members",
             "kind": "function",
             "path": "docforge.renderers.mcp_renderer.DocObject.get_all_members",
             "signature": "<bound method Alias.signature of Alias('get_all_members', 'docforge.models.object.DocObject.get_all_members')>",
-            "docstring": "Return all child members of the object.\n\nReturns:\n    An iterable of ``DocObject`` instances representing nested members."
+            "docstring": "Get all members of this object.\n\nReturns:\n    An iterable of child DocObject instances."
           }
         }
       },
@@ -210,8 +210,8 @@
         "name": "MCPRenderer",
         "kind": "class",
         "path": "docforge.renderers.mcp_renderer.MCPRenderer",
-        "signature": "<bound method Class.signature of Class('MCPRenderer', 8, 138)>",
-        "docstring": "Renderer that generates MCP-compatible documentation resources.\n\nThis renderer converts doc-forge project models into structured JSON\nresources suitable for consumption by systems implementing the Model\nContext Protocol (MCP).",
+        "signature": "<bound method Class.signature of Class('MCPRenderer', 8, 122)>",
+        "docstring": "Renderer that emits MCP-native JSON resources from docforge models.",
         "members": {
           "name": {
             "name": "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', 19, 60)>",
-            "docstring": "Generate MCP documentation resources for a project.\n\nThe renderer serializes each module into a JSON resource and produces\nsupporting metadata files such as ``nav.json`` and ``index.json``.\n\nArgs:\n    project: Documentation project model to render.\n    out_dir: Directory where MCP resources will be written."
+            "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": "MkDocs renderer implementation.\n\nThis module defines the ``MkDocsRenderer`` class, which generates Markdown\ndocumentation sources compatible with MkDocs Material and the mkdocstrings\nplugin.\n\nThe renderer ensures a consistent documentation structure by:\n\n- Creating a root ``index.md`` if one does not exist\n- Generating package index pages automatically\n- Linking child modules within parent package pages\n- Optionally generating ``README.md`` from the root package docstring",
+    "docstring": "This module implements the MkDocsRenderer, which generates Markdown source files\ncompatible with the MkDocs 'material' theme and 'mkdocstrings' extension.",
     "objects": {
       "Path": {
         "name": "Path",
@@ -16,7 +16,7 @@
         "kind": "class",
         "path": "docforge.renderers.mkdocs_renderer.Project",
         "signature": "<bound method Alias.signature of Alias('Project', 'docforge.models.Project')>",
-        "docstring": "Representation of a documentation project.\n\nA ``Project`` serves as the root container for all modules discovered during\nintrospection. Each module is stored by its dotted import path.\n\nAttributes:\n    name: Name of the project.\n    modules: Mapping of module paths to ``Module`` instances.",
+        "docstring": "Represents a documentation project, serving as a container for modules.\n\nAttributes:\n    name: Name of the project.\n    modules: Dictionary mapping module paths to Module instances.",
         "members": {
           "name": {
             "name": "name",
@@ -37,37 +37,67 @@
             "kind": "function",
             "path": "docforge.renderers.mkdocs_renderer.Project.add_module",
             "signature": "<bound method Alias.signature of Alias('add_module', 'docforge.models.project.Project.add_module')>",
-            "docstring": "Register a module in the project.\n\nArgs:\n    module: Module instance to add to the project."
+            "docstring": "Add a module to the project.\n\nArgs:\n    module: The module to add."
           },
           "get_module": {
             "name": "get_module",
             "kind": "function",
             "path": "docforge.renderers.mkdocs_renderer.Project.get_module",
             "signature": "<bound method Alias.signature of Alias('get_module', 'docforge.models.project.Project.get_module')>",
-            "docstring": "Retrieve a module by its dotted path.\n\nArgs:\n    path: Fully qualified dotted module path (for example ``pkg.module``).\n\nReturns:\n    The corresponding ``Module`` instance.\n\nRaises:\n    KeyError: If the module does not exist in the project."
+            "docstring": "Retrieve a module by its dotted path.\n\nArgs:\n    path: The dotted path of the module (e.g., 'pkg.mod').\n\nReturns:\n    The requested Module."
           },
           "get_all_modules": {
             "name": "get_all_modules",
             "kind": "function",
             "path": "docforge.renderers.mkdocs_renderer.Project.get_all_modules",
             "signature": "<bound method Alias.signature of Alias('get_all_modules', 'docforge.models.project.Project.get_all_modules')>",
-            "docstring": "Return all modules contained in the project.\n\nReturns:\n    An iterable of ``Module`` instances."
+            "docstring": "Get all modules in the project.\n\nReturns:\n    An iterable of Module objects."
           },
           "get_module_list": {
             "name": "get_module_list",
             "kind": "function",
             "path": "docforge.renderers.mkdocs_renderer.Project.get_module_list",
             "signature": "<bound method Alias.signature of Alias('get_module_list', 'docforge.models.project.Project.get_module_list')>",
-            "docstring": "Return the list of module import paths.\n\nReturns:\n    A list containing the dotted paths of all modules in the project."
+            "docstring": "Get the list of all module dotted paths.\n\nReturns:\n    A list of module paths."
           }
         }
       },
+      "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",
         "path": "docforge.renderers.mkdocs_renderer.Module",
         "signature": "<bound method Alias.signature of Alias('Module', 'docforge.models.Module')>",
-        "docstring": "Representation of a documented Python module or package.\n\nA ``Module`` stores metadata about the module itself and maintains a\ncollection of top-level documentation objects discovered during\nintrospection.\n\nAttributes:\n    path: Dotted import path of the module.\n    docstring: Module-level documentation string, if present.\n    members: Mapping of object names to their corresponding\n        ``DocObject`` representations.",
+        "docstring": "Represents a documented Python module or package.\n\nAttributes:\n    path: Dotted import path of the module.\n    docstring: Module-level docstring content.\n    members: Dictionary mapping object names to their DocObject representations.",
         "members": {
           "path": {
             "name": "path",
@@ -95,51 +125,21 @@
             "kind": "function",
             "path": "docforge.renderers.mkdocs_renderer.Module.add_object",
             "signature": "<bound method Alias.signature of Alias('add_object', 'docforge.models.module.Module.add_object')>",
-            "docstring": "Add a documented object to the module.\n\nArgs:\n    obj: Documentation object to register as a top-level\n        member of the module."
+            "docstring": "Add a documented object to the module.\n\nArgs:\n    obj: The object to add."
           },
           "get_object": {
             "name": "get_object",
             "kind": "function",
             "path": "docforge.renderers.mkdocs_renderer.Module.get_object",
             "signature": "<bound method Alias.signature of Alias('get_object', 'docforge.models.module.Module.get_object')>",
-            "docstring": "Retrieve a documented object by name.\n\nArgs:\n    name: Name of the object to retrieve.\n\nReturns:\n    The corresponding ``DocObject`` instance.\n\nRaises:\n    KeyError: If no object with the given name exists."
+            "docstring": "Retrieve a member object by name.\n\nArgs:\n    name: The name of the object.\n\nReturns:\n    The requested DocObject."
           },
           "get_all_objects": {
             "name": "get_all_objects",
             "kind": "function",
             "path": "docforge.renderers.mkdocs_renderer.Module.get_all_objects",
             "signature": "<bound method Alias.signature of Alias('get_all_objects', 'docforge.models.module.Module.get_all_objects')>",
-            "docstring": "Return all top-level documentation objects in the module.\n\nReturns:\n    An iterable of ``DocObject`` instances representing the\n    module's public members."
-          }
-        }
-      },
-      "MkDocsRenderer": {
-        "name": "MkDocsRenderer",
-        "kind": "class",
-        "path": "docforge.renderers.mkdocs_renderer.MkDocsRenderer",
-        "signature": "<bound method Class.signature of Class('MkDocsRenderer', 20, 272)>",
-        "docstring": "Renderer that produces Markdown documentation for MkDocs.\n\nGenerated pages use mkdocstrings directives to reference Python modules,\nallowing MkDocs to render API documentation dynamically.",
-        "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', 34, 71)>",
-            "docstring": "Generate Markdown documentation files for a project.\n\nThis method renders a documentation structure from the provided\nproject model and writes the resulting Markdown files to the\nspecified output directory.\n\nArgs:\n    project: Project model containing modules to document.\n    out_dir: Directory where generated Markdown files will be written.\n    module_is_source: If True, treat the specified module as the\n        documentation root rather than nesting it inside a folder."
-          },
-          "generate_readme": {
-            "name": "generate_readme",
-            "kind": "function",
-            "path": "docforge.renderers.mkdocs_renderer.MkDocsRenderer.generate_readme",
-            "signature": "<bound method Function.signature of Function('generate_readme', 73, 128)>",
-            "docstring": "Generate a ``README.md`` file from the root module docstring.\n\nBehavior:\n\n- If ``module_is_source`` is True, ``README.md`` is written to the\n  project root directory.\n- If False, README generation is currently not implemented.\n\nArgs:\n    project: Project model containing documentation metadata.\n    docs_dir: Directory containing generated documentation sources.\n    module_is_source: Whether the module is treated as the project\n        source root."
+            "docstring": "Get all top-level objects in the module.\n\nReturns:\n    An iterable of DocObject instances."
           }
         }
       }

mcp_docs/modules/docforge.servers.json

@@ -2,14 +2,14 @@
   "module": "docforge.servers",
   "content": {
     "path": "docforge.servers",
-    "docstring": "Server layer for doc-forge.\n\nThis module exposes server implementations used to provide live access\nto generated documentation resources. Currently, it includes the MCP\ndocumentation server.\n\n---",
+    "docstring": null,
     "objects": {
       "MCPServer": {
         "name": "MCPServer",
         "kind": "class",
         "path": "docforge.servers.MCPServer",
         "signature": "<bound method Alias.signature of Alias('MCPServer', 'docforge.servers.mcp_server.MCPServer')>",
-        "docstring": "MCP server for serving a pre-generated documentation bundle.\n\nThe server exposes documentation resources and diagnostic tools through\nMCP endpoints backed by JSON files generated by the MCP renderer.",
+        "docstring": "MCP server for serving a pre-built MCP documentation bundle.",
         "members": {
           "mcp_root": {
             "name": "mcp_root",
@@ -30,7 +30,7 @@
             "kind": "function",
             "path": "docforge.servers.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: Transport mechanism used by the MCP server. Supported\n        options include ``stdio``, ``sse``, and ``streamable-http``."
+            "docstring": "Start the MCP server.\n\nArgs:\n    transport: MCP transport (default: streamable-http)"
           }
         }
       },
@@ -87,8 +87,8 @@
             "name": "MCPServer",
             "kind": "class",
             "path": "docforge.servers.mcp_server.MCPServer",
-            "signature": "<bound method Class.signature of Class('MCPServer', 10, 122)>",
-            "docstring": "MCP server for serving a pre-generated documentation bundle.\n\nThe server exposes documentation resources and diagnostic tools through\nMCP endpoints backed by JSON files generated by the MCP renderer.",
+            "signature": "<bound method Class.signature of Class('MCPServer', 10, 95)>",
+            "docstring": "MCP server for serving a pre-built MCP documentation bundle.",
             "members": {
               "mcp_root": {
                 "name": "mcp_root",
@@ -108,8 +108,8 @@
                 "name": "run",
                 "kind": "function",
                 "path": "docforge.servers.mcp_server.MCPServer.run",
-                "signature": "<bound method Function.signature of Function('run', 111, 122)>",
-                "docstring": "Start the MCP server.\n\nArgs:\n    transport: Transport mechanism used by the MCP server. Supported\n        options include ``stdio``, ``sse``, and ``streamable-http``."
+                "signature": "<bound method Function.signature of Function('run', 88, 95)>",
+                "docstring": "Start the MCP server.\n\nArgs:\n    transport: MCP transport (default: streamable-http)"
               }
             }
           }

mcp_docs/modules/docforge.servers.mcp_server.json

@@ -50,8 +50,8 @@
         "name": "MCPServer",
         "kind": "class",
         "path": "docforge.servers.mcp_server.MCPServer",
-        "signature": "<bound method Class.signature of Class('MCPServer', 10, 122)>",
-        "docstring": "MCP server for serving a pre-generated documentation bundle.\n\nThe server exposes documentation resources and diagnostic tools through\nMCP endpoints backed by JSON files generated by the MCP renderer.",
+        "signature": "<bound method Class.signature of Class('MCPServer', 10, 95)>",
+        "docstring": "MCP server for serving a pre-built MCP documentation bundle.",
         "members": {
           "mcp_root": {
             "name": "mcp_root",
@@ -71,8 +71,8 @@
             "name": "run",
             "kind": "function",
             "path": "docforge.servers.mcp_server.MCPServer.run",
-            "signature": "<bound method Function.signature of Function('run', 111, 122)>",
-            "docstring": "Start the MCP server.\n\nArgs:\n    transport: Transport mechanism used by the MCP server. Supported\n        options include ``stdio``, ``sse``, and ``streamable-http``."
+            "signature": "<bound method Function.signature of Function('run', 88, 95)>",
+            "docstring": "Start the MCP server.\n\nArgs:\n    transport: MCP transport (default: streamable-http)"
           }
         }
       }

mkdocs.yml

@@ -1,3 +1,5 @@
+site_name: docforge
+
 theme:
   name: material
   palette:
@@ -8,19 +10,12 @@ theme:
     text: Inter
     code: JetBrains Mono
   features:
-  - navigation.sections
+  - navigation.tabs
   - navigation.expand
   - navigation.top
   - navigation.instant
-  - navigation.tracking
-  - navigation.indexes
   - content.code.copy
   - content.code.annotate
-  - content.tabs.link
-  - content.action.edit
-  - search.highlight
-  - search.share
-  - search.suggest
 plugins:
 - search
 - mkdocstrings:
@@ -38,54 +33,30 @@ plugins:
           annotations_path: brief
           show_root_heading: true
           group_by_category: true
-          show_category_heading: true
-          show_object_full_path: false
-          show_symbol_type_heading: true
-markdown_extensions:
-- pymdownx.superfences
-- pymdownx.inlinehilite
-- pymdownx.snippets
-- admonition
-- pymdownx.details
-- pymdownx.superfences
-- pymdownx.highlight:
-    linenums: true
-    anchor_linenums: true
-    line_spans: __span
-    pygments_lang_class: true
-- pymdownx.tabbed:
-    alternate_style: true
-- pymdownx.tasklist:
-    custom_checkbox: true
-- tables
-- footnotes
-- pymdownx.caret
-- pymdownx.tilde
-- pymdownx.mark
-site_name: docforge
+
 nav:
-- Home: index.md
+- Home: docforge/index.md
 - Loaders:
-  - loaders/index.md
-  - loaders/griffe_loader.md
+  - docforge/loaders/index.md
+  - docforge/loaders/griffe_loader.md
 - Models:
-  - models/index.md
-  - models/module.md
-  - models/object.md
-  - models/project.md
+  - docforge/models/index.md
+  - docforge/models/module.md
+  - docforge/models/object.md
+  - docforge/models/project.md
 - Navigation:
-  - nav/index.md
-  - nav/spec.md
-  - nav/resolver.md
-  - nav/mkdocs.md
+  - docforge/nav/index.md
+  - docforge/nav/spec.md
+  - docforge/nav/resolver.md
+  - docforge/nav/mkdocs.md
 - Renderers:
-  - renderers/index.md
-  - renderers/base.md
-  - renderers/mkdocs_renderer.md
-  - renderers/mcp_renderer.md
+  - docforge/renderers/index.md
+  - docforge/renderers/base.md
+  - docforge/renderers/mkdocs_renderer.md
+  - docforge/renderers/mcp_renderer.md
 - CLI:
-  - cli/index.md
-  - cli/main.md
-  - cli/commands.md
-  - cli/mcp_utils.md
-  - cli/mkdocs_utils.md
+  - docforge/cli/index.md
+  - docforge/cli/main.md
+  - docforge/cli/commands.md
+  - docforge/cli/mcp_utils.md
+  - docforge/cli/mkdocs_utils.md

pyproject.toml

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

tests/cli/test_serve_mcp.py

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

tests/renderers/mkdocs/test_mkdocs_content.py

@@ -17,34 +17,3 @@ def test_mkdocs_file_content(tmp_path: Path):
 
     assert "# Mod" in content
     assert "::: testpkg.mod" in content
-
-
-def test_generate_readme_source_root(tmp_path: Path):
-    project = Project("testpkg")
-
-    root = Module("testpkg")
-    root.docstring = "Test package documentation."
-
-    project.add_module(root)
-    project.add_module(Module("testpkg.mod"))
-
-    docs_dir = tmp_path / "docs"
-
-    renderer = MkDocsRenderer()
-
-    renderer.generate_sources(project, docs_dir)
-
-    renderer.generate_readme(
-        project,
-        docs_dir,
-        module_is_source=True,
-    )
-
-    readme = tmp_path / "README.md"
-
-    assert readme.exists()
-
-    content = readme.read_text()
-
-    assert "# testpkg" in content
-    assert "Test package documentation." in content

tests/renderers/mkdocs/test_mkdocs_idempotency.py

@@ -18,36 +18,3 @@ def test_mkdocs_idempotent(tmp_path: Path):
     second = (out_dir / "testpkg" / "mod.md").read_text()
 
     assert first == second
-
-
-def test_generate_readme_idempotent(tmp_path: Path):
-    project = Project("testpkg")
-
-    root = Module("testpkg")
-    root.docstring = "Test package documentation."
-
-    project.add_module(root)
-
-    docs_dir = tmp_path / "docs"
-
-    renderer = MkDocsRenderer()
-
-    renderer.generate_readme(
-        project,
-        docs_dir,
-        module_is_source=True,
-    )
-
-    readme = tmp_path / "README.md"
-
-    first = readme.read_text()
-
-    renderer.generate_readme(
-        project,
-        docs_dir,
-        module_is_source=True,
-    )
-
-    second = readme.read_text()
-
-    assert first == second

tests/renderers/mkdocs/test_mkdocs_module_coverage.py

@@ -17,12 +17,6 @@ def test_mkdocs_emits_all_modules(tmp_path: Path) -> None:
     renderer = MkDocsRenderer()
     renderer.generate_sources(project, tmp_path)
 
-    renderer.generate_readme(
-        project,
-        tmp_path,
-        module_is_source=True,
-    )
-
     emitted = {
         p.relative_to(tmp_path).as_posix()
         for p in tmp_path.rglob("*.md")
@@ -45,8 +39,3 @@ def test_mkdocs_emits_all_modules(tmp_path: Path) -> None:
 
     missing = expected - emitted
     assert not missing, f"Missing markdown files for modules: {missing}"
-
-    readme = tmp_path.parent / "README.md"
-    assert readme.exists(), "README.md was not generated"
-    content = readme.read_text(encoding="utf-8")
-    assert project.name in content

tests/renderers/mkdocs/test_mkdocs_structure.py

@@ -13,12 +13,6 @@ def test_mkdocs_directory_structure(tmp_path: Path):
     renderer = MkDocsRenderer()
 
     renderer.generate_sources(project, out_dir)
-    renderer.generate_readme(
-        project,
-        out_dir,
-        module_is_source=True,
-    )
 
     assert (out_dir / "testpkg" / "index.md").exists()
     assert (out_dir / "testpkg" / "sub.md").exists()
-    assert (tmp_path / "README.md").exists()