docs, cli: enforce package-bound docs, add template scaffolding, and document CLI usage

- Restrict mkdocstrings generation to real Python packages (require __init__.py)
- Add explicit documentation section for CLI scaffolding and templates
- Generalize CLI to support multiple templates with dynamic discovery
- Package templates correctly for importlib.resources access
- Add fully documented health_app template (app entry point and handlers)
- Fix setuptools package-data configuration for bundled templates

These changes make documentation import-safe, clarify package boundaries,
and provide a deterministic, OpenAPI-first scaffolding workflow via CLI.

manage_docs.py

@@ -68,28 +68,42 @@ def generate_docs_from_nav(
 
     docs_root.mkdir(parents=True, exist_ok=True)
 
-    for py_file in package_dir.rglob("*.py"):
-        rel = py_file.relative_to(project_root)
+    # Collect all package directories (those containing __init__.py)
+    package_dirs: set[Path] = {
+        p.parent
+        for p in package_dir.rglob("__init__.py")
+    }
 
-        if py_file.name == "__init__.py":
-            # Package → index.md
-            module_path = ".".join(rel.parent.parts)
-            md_path = docs_root / rel.parent / "index.md"
-            title = rel.parent.name.replace("_", " ").title()
-        else:
-            # Regular module → <module>.md
-            module_path = ".".join(rel.with_suffix("").parts)
-            md_path = docs_root / rel.with_suffix(".md")
-            title = md_path.stem.replace("_", " ").title()
+    for pkg_dir in sorted(package_dirs):
+        rel_pkg = pkg_dir.relative_to(project_root)
+        module_base = ".".join(rel_pkg.parts)
 
-        md_path.parent.mkdir(parents=True, exist_ok=True)
+        # index.md for the package itself
+        index_md = docs_root / rel_pkg / "index.md"
+        index_md.parent.mkdir(parents=True, exist_ok=True)
 
-        content = f"""# {title}
+        title = pkg_dir.name.replace("_", " ").title()
+        index_md.write_text(
+            f"# {title}\n\n::: {module_base}\n",
+            encoding="utf-8",
+        )
 
-::: {module_path}
-"""
+        # Document modules inside this package only
+        for py_file in pkg_dir.iterdir():
+            if (
+                    py_file.suffix != ".py"
+                    or py_file.name == "__init__.py"
+            ):
+                continue
 
-        md_path.write_text(content, encoding="utf-8")
+            module_path = f"{module_base}.{py_file.stem}"
+            md_path = docs_root / rel_pkg / f"{py_file.stem}.md"
+
+            title = py_file.stem.replace("_", " ").title()
+            md_path.write_text(
+                f"# {title}\n\n::: {module_path}\n",
+                encoding="utf-8",
+            )
 
 
 def load_mkdocs_config():