chore(release): 0.0.7

Squash-merge lib-standardisation: adopt repo standards across packaging,
tooling, docs, and CI.

- standardize pyproject.toml (canonical packaging, lint config, extras, GSDFC pydoclint)
- add py.typed marker, modernize type hints and Google-style docstrings
- nest generated docs under docs/lib and docs/mcp; add hand-written wiki
- adopt standard Type A PyPI CI pipeline (tag==version guard + quality gate)
- promote generated CHANGELOG.md; bump version to 0.0.7

docforge/nav/spec.py

@@ -4,10 +4,20 @@ 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``).
+
+---
+
+Notes:
+    - The spec file supports an optional ``icon`` mapping for MkDocs theme
+      customization.
+    - All file references in ``groups`` are relative to the documentation root.
+
+---
 """
 
+from __future__ import annotations
+
 from pathlib import Path
-from typing import Dict, List, Optional
 
 import yaml
 
@@ -24,34 +34,46 @@ class NavSpec:
             ``index.md``).
         groups: Mapping of navigation group titles to lists of file patterns
             or glob expressions.
+        icon: Optional mapping of theme icon entries (for example
+            ``{"logo": "material/code-tags"}``) injected into the MkDocs
+            theme as ``theme.icon``.
     """
 
     def __init__(
         self,
-        home: Optional[str],
-        groups: Dict[str, List[str]],
+        home: str | None,
+        groups: dict[str, list[str]],
+        icon: dict[str, str] | None = None,
     ) -> None:
         """
         Initialize a NavSpec instance.
 
         Args:
-            home: Relative path to the home document.
-            groups: Mapping of group names to lists of path patterns
+            home (str | None):
+                Relative path to the home document.
+            groups (dict[str, list[str]]):
+                Mapping of group names to lists of path patterns
                 (glob expressions).
+            icon (dict[str, str] | None):
+                Optional mapping of theme icon entries applied to the
+                generated MkDocs configuration.
         """
         self.home = home
         self.groups = groups
+        self.icon = icon
 
     @classmethod
-    def load(cls, path: Path) -> "NavSpec":
+    def load(cls, path: Path) -> NavSpec:
         """
         Load a navigation specification from a YAML file.
 
         Args:
-            path: Filesystem path to the navigation specification file.
+            path (Path):
+                Filesystem path to the navigation specification file.
 
         Returns:
-            A ``NavSpec`` instance representing the parsed configuration.
+            NavSpec:
+                A ``NavSpec`` instance representing the parsed configuration.
 
         Raises:
             FileNotFoundError: If the specified file does not exist.
@@ -68,6 +90,7 @@ class NavSpec:
 
         home = data.get("home")
         groups = data.get("groups", {})
+        icon = data.get("icon")
 
         if home is not None and not isinstance(home, str):
             raise ValueError("home must be a string")
@@ -83,17 +106,26 @@ class NavSpec:
             ):
                 raise ValueError(f"group '{key}' must be a list of strings")
 
-        return cls(home=home, groups=groups)
+        if icon is not None and (
+            not isinstance(icon, dict)
+            or not all(
+                isinstance(k, str) and isinstance(v, str) for k, v in icon.items()
+            )
+        ):
+            raise ValueError("icon must be a mapping of strings")
 
-    def all_patterns(self) -> List[str]:
+        return cls(home=home, groups=groups, icon=icon)
+
+    def all_patterns(self) -> list[str]:
         """
         Return all path patterns referenced by the specification.
 
         Returns:
-            A list containing the home document (if defined) and all
-            group pattern entries.
+            list[str]:
+                A list containing the home document (if defined) and all
+                group pattern entries.
         """
-        patterns: List[str] = []
+        patterns: list[str] = []
 
         if self.home:
             patterns.append(self.home)
@@ -112,10 +144,12 @@ def load_nav_spec(path: Path) -> NavSpec:
     corresponding ``NavSpec`` instance.
 
     Args:
-        path: Path to the navigation specification file.
+        path (Path):
+            Path to the navigation specification file.
 
     Returns:
-        A ``NavSpec`` instance representing the parsed specification.
+        NavSpec:
+            A ``NavSpec`` instance representing the parsed specification.
 
     Raises:
         FileNotFoundError: If the specification file does not exist.
@@ -132,4 +166,5 @@ def load_nav_spec(path: Path) -> NavSpec:
     return NavSpec(
         home=data.get("home"),
         groups=data.get("groups", {}),
+        icon=data.get("icon"),
     )