PythonWoods · PythonWoods · Jan 23, 2026 · Jan 23, 2026 · Jan 23, 2026
diff --git a/docs/_snippets/core_modules_list.rst b/docs/_snippets/core_modules_list.rst
@@ -1,6 +1,3 @@
-.. SPDX-FileCopyrightText: 2026 PythonWoods
-.. SPDX-License-Identifier: Apache-2.0
-
 - :doc:`modules/auth` - Authentication and authorization interfaces
 - :doc:`modules/configuration` - Multi-layer config with dot-notation
 - :doc:`modules/database` - Connection pooling, transactions, health checks

diff --git a/docs/_snippets/plugins_list.rst b/docs/_snippets/plugins_list.rst
@@ -1,6 +1,3 @@
-.. SPDX-FileCopyrightText: 2026 PythonWoods
-.. SPDX-License-Identifier: Apache-2.0
-
 - :doc:`plugins/auth` - Authentication implementations
 - :doc:`plugins/bootstrap` - Application lifecycle management
 - :doc:`plugins/cli-tools` - Advanced development tools

diff --git a/docs/conf.py b/docs/conf.py
@@ -77,11 +77,36 @@ def token(varname: str, default: str) -> str:
 
 # Configura Furo con force dark options
 html_theme_options = {
-    "source_repository": "https://github.com/PythonWoods/structum/",
-    "source_branch": "main",
-    "source_directory": "docs/",
-    "top_of_page_button": "edit",
-    "navigation_with_keys": True,
+    "repo_url": "https://github.com/PythonWoods/structum",
+    "repo_name": "PythonWoods/structum",
+    "edit_uri": "edit/main/docs",
+    "font": {"text": "Roboto", "code": "Roboto Mono"},
+    "icon": {"repo": "fontawesome/brands/github", "edit": "material/file-edit-outline"},
+    "palette": [
+        {
+            "media": "(prefers-color-scheme: light)",
+            "scheme": "default",
+            "primary": "indigo",
+            "accent": "indigo",
+        },
+        {
+            "media": "(prefers-color-scheme: dark)",
+            "scheme": "slate",
+            "primary": "indigo",
+            "accent": "indigo",
+        },
+    ],
+    "features": [
+        "navigation.expand",
+        "navigation.tabs",
+        "navigation.top",
+        "navigation.sections",
+        "navigation.indexes",
+        "navigation.instant",  # Improve navigation speed
+        "header.autohide",  # Auto-hide header on scroll
+        "search.share",  # Share search results
+    ],
+    "globaltoc_collapse": False,
 }
 
 # -- Autodoc/Napoleon/Exclude -----------------------------------------------

diff --git a/docs/index.rst b/docs/index.rst
@@ -6,108 +6,77 @@ Structum Framework
 
 .. raw:: html
 
-   <link rel="stylesheet" href="_static/dark-theme.css">
-
-   <div class="hero">
-     <div class="hero-content">
-       <h1>STRUCTUM</h1>
-       <p>Protocol-Based · AI-Assisted · Human-Governed</p>
-       <a href="installation.html" class="btn-hero">Get Started</a>
-     </div>
-   </div>
-
-----
-
-Core Philosophy
----------------
-
-.. grid:: 2
-   :gutter: 3
-   :padding: 0
-   :class-container: features-grid
-
-   .. grid-item-card:: 
-      :class-card: feature-card
-      :text-align: left
-      :shadow: none
-
-      **Protocol-First Architecture**
-      ^^^
-      Built on ``typing.Protocol`` interfaces. Decoupled and testable.
-
-   .. grid-item-card::
-      :class-card: feature-card
-      :text-align: left
-      :shadow: none
-
-      **Zero Dependency Core**
-      ^^^
-      Pure Python Standard Library. Secure and lightweight.
-
-   .. grid-item-card::
-      :class-card: feature-card
-      :text-align: left
-      :shadow: none
-
-      **Production-Hardened**
-      ^^^
-      Health checks, metrics, and graceful shutdown included.
-
-   .. grid-item-card::
-      :class-card: feature-card
-      :text-align: left
-      :shadow: none
-
-      **Modular by Design**
-      ^^^
-      Install only what you need. No forced dependencies.
-
-.. tab-set::
-
-   .. tab-item:: New Project
-
-      .. code-block:: bash
-
-         # Pre-Alpha: Install from source
-         git clone https://github.com/PythonWoods/structum.git
-         cd structum
-         ./scripts/setup_dev.sh
-
-      .. tip::
-
-         Generates: Config management, health endpoints, logging, CLI, tests
-
-   .. tab-item:: Existing Project
-
-      .. code-block:: bash
-
-         # Pre-Alpha: Install as editable
-         pip install -e /path/to/structum
-
-      .. code-block:: python
-
-         from structum import Config, inject
-
-         @inject
-         def my_function(config: Config):
-             db_url = config.database.url  # Dot-notation access
-
-   .. tab-item:: Docker
-
-      .. code-block:: dockerfile
-
-         # Build a lightweight image
-         FROM python:3.11-slim-bookworm
-         WORKDIR /app
-         COPY requirements.txt .
-         RUN pip install -r requirements.txt
-         COPY . .
-         CMD ["python", "main.py"]
-
-----
-
-Plugin Ecosystem
-----------------
+   <span id="installation"></span>
+
+Installation
+------------
+
+.. include:: _snippets/warning_alpha.rst
+
+For detailed instructions and prerequisites (including **uv** setup), see the :doc:`installation` guide.
+
+Quick Install (From Source)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. include:: _snippets/install_source.rst
+
+.. note::
+   This installs all workspace packages in editable mode. See :doc:`installation` for details.
+
+Quick Start
+-----------
+
+The configuration system works out-of-the-box without any setup using ``structum``:
+
+.. code-block:: python
+
+    from structum.config import get_config
+
+    # Get the singleton instance
+    config = get_config()
+
+    # Write configuration (automatically persisted)
+    config.set("server.host", "0.0.0.0")
+    config.set("server.port", 8080)
+
+    # Read configuration (with safe defaults)
+    host = config.get("server.host", default="localhost")
+    port = config.get("server.port", default=8000)
+
+    print(f"Server starting on {host}:{port}")
+
+For a complete guide on building a production-ready application with plugins, see the :doc:`guides/user_tutorial`.
+
+Architecture Overview
+---------------------
+
+Protocol-Based Design
+~~~~~~~~~~~~~~~~~~~~~
+
+Structum separates **interfaces** (protocols) from **implementations** (plugins):
+
+.. code-block:: text
+
+    ┌─────────────────────────────────────────┐
+    │   Application Code                      │
+    │   Uses: get_config(), get_logger()      │
+    └──────────────────┬──────────────────────┘
+                       │
+    ┌──────────────────▼──────────────────────┐
+    │   Structum Core (structum)         │
+    │   • ConfigProviderInterface             │
+    │   • LoggerInterface                     │
+    │   • AuthInterface                       │
+    │   • DatabaseInterface                   │
+    └──────────────────┬──────────────────────┘
+                       │
+    ┌──────────────────▼──────────────────────┐
+    │   Plugin Implementations                │
+    │   ┌──────────┬──────────┬──────────┐   │
+    │   │ Dynaconf │Observable│ Auth     │   │
+    │   │ Provider │ Logger   │ Provider │   │
+    │   └──────────┴──────────┴──────────┘   │
+    └─────────────────────────────────────────┘
 
 Structum leverages a modular architecture where the **Core** provides stability and interfaces, while **Plugins** provide implementation details.
 
@@ -148,7 +117,38 @@ Planned Official Plugins
 - **structum-celery**: Background task processing
 - **structum-sentry**: Error tracking
 
-----
+Instead of manually wiring ``pydantic``, ``structlog``, ``prometheus_client``, Structum provides a unified API with consistent patterns.
+
+vs No Framework
+~~~~~~~~~~~~~~~
+
+As projects grow, you'll reinvent configuration management, logging setup, health checks. Structum provides these patterns from day one.
+
+Next Steps
+----------
+
+1. :doc:`guides/user_tutorial` - Build your first application
+2. **Explore Core Modules**:
+
+   - :doc:`modules/configuration`
+   - :doc:`modules/logging`
+   - :doc:`modules/auth`
+   - :doc:`modules/database`
+   - :doc:`modules/monitoring`
+
+3. :doc:`guides/enterprise_architecture` - Building production systems
+4. :doc:`reference/core` - Complete API documentation
+
+Support
+-------
+
+- **GitHub Issues**: `github.com/PythonWoods/structum/issues <https://github.com/PythonWoods/structum/issues>`_
+- **Discussions**: `github.com/PythonWoods/structum/discussions <https://github.com/PythonWoods/structum/discussions>`_
+
+License
+-------
+
+Apache 2.0 - See `LICENSE <https://github.com/PythonWoods/structum/blob/main/LICENSE>`_
 
 .. toctree::
    :maxdepth: 2

diff --git a/docs/modules/index.rst b/docs/modules/index.rst
@@ -1,5 +1,4 @@
-.. SPDX-FileCopyrightText: 2026 PythonWoods
-.. SPDX-License-Identifier: Apache-2.0
+Core Modules
 
 Core Modules
 ============

diff --git a/packages/structum/src/structum/auth/interfaces.py b/packages/structum/src/structum/auth/interfaces.py
@@ -32,12 +32,6 @@ class TokenPair:
     """
     Data class containing JWT access and refresh token pair.
 
-    Attributes:
-        access_token (str): Short-lived JWT access token for API requests.
-        refresh_token (str): Long-lived token for obtaining new access tokens.
-        token_type (str): Token type, typically "bearer" for JWT. Defaults to "bearer".
-        expires_at (datetime | None): Expiration timestamp for access token, if available.
-
     Example:
         Creating and using token pair::
 
@@ -61,9 +55,16 @@ class TokenPair:
     """
 
     access_token: str
+    """Short-lived JWT access token for API requests."""
+
     refresh_token: str
+    """Long-lived token for obtaining new access tokens."""
+
     token_type: str = "bearer"
+    """Token type, typically "bearer" for JWT. Defaults to "bearer"."""
+
     expires_at: datetime | None = None
+    """Expiration timestamp for access token, if available."""
 
 
 @runtime_checkable

diff --git a/packages/structum/src/structum/database/interfaces.py b/packages/structum/src/structum/database/interfaces.py
@@ -56,13 +56,6 @@ class HealthCheckResult:
     """
     Data class representing database health check results.
 
-    Attributes:
-        status (HealthStatus): Overall health status (HEALTHY, DEGRADED, UNHEALTHY).
-        message (str): Human-readable status description.
-        latency_ms (float | None): Query latency in milliseconds, if available.
-        details (dict[str, Any] | None): Additional diagnostic information
-            (e.g., active connections, pool statistics).
-
     Example:
         Creating and using a health check result::
 
@@ -83,9 +76,16 @@ class HealthCheckResult:
     """
 
     status: HealthStatus
+    """Overall health status (HEALTHY, DEGRADED, UNHEALTHY)."""
+
     message: str
+    """Human-readable status description."""
+
     latency_ms: float | None = None
+    """Query latency in milliseconds, if available."""
+
     details: dict[str, Any] | None = None
+    """Additional diagnostic information (e.g., active connections, pool statistics)."""
 
 
 @runtime_checkable