docforge/__init__.py

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