added docs strings

docforge/__init__.py

@@ -1,9 +1,54 @@
 """
-doc-forge — renderer-agnostic Python documentation compiler.
+# doc-forge
 
-At this stage, doc-forge publicly exposes only the Introspection Layer.
-All the rendering, exporting, and serving APIs are intentionally private
-until their contracts are finalized.
+`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 model.
+
+## Installation
+
+Install using `pip` with the optional `mkdocs` dependencies for a complete setup:
+
+```bash
+pip install doc-forge
+```
+
+## Quick Start
+
+1.  **Generate Markdown Sources**:
+    Introspect your package and create ready-to-use Markdown files:
+    ```bash
+    doc-forge generate --module my_package --docs-dir docs
+    ```
+
+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.  **Generate MkDocs Configuration**:
+    ```bash
+    doc-forge mkdocs --site-name "My Awesome Docs"
+    ```
+
+4.  **Preview**:
+    ```bash
+    doc-forge serve
+    ```
+
+## Project Structure
+
+- `docforge.loader`: Introspects source code using static analysis (`griffe`).
+- `docforge.model`: The internal representation of your project, modules, and objects.
+- `docforge.renderers`: Converters that turn the model into physical files.
+- `docforge.nav`: Managers for logical-to-physical path mapping and navigation.
 """
 
 from .loader import GriffeLoader, discover_module_paths