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.

openapi_first/templates/__init__.py

@@ -0,0 +1,18 @@
+"""
+Application templates for FastAPI OpenAPI First.
+
+This package contains example and scaffolding templates intended to be
+copied into user projects via the ``openapi-first`` CLI.
+
+Templates in this package are:
+- Reference implementations of OpenAPI-first services
+- Not part of the ``openapi_first`` public or internal API
+- Not intended to be imported as runtime dependencies
+
+The presence of this file exists solely to:
+- Mark the directory as an explicit Python package
+- Enable deterministic tooling behavior (documentation, packaging)
+- Avoid accidental traversal of non-package directories
+
+No code in this package should be imported by library consumers.
+"""

openapi_first/templates/health_app/__init__.py

@@ -0,0 +1,65 @@
+"""
+OpenAPI-first FastAPI application template.
+
+This package contains a minimal, fully working example of an
+OpenAPI-first FastAPI service built using the ``openapi_first`` library.
+
+The application is assembled exclusively from:
+- an OpenAPI specification (``openapi.yaml``)
+- a handler namespace (``routes``)
+
+No routing decorators, implicit behavior, or framework-specific
+convenience abstractions are used. All HTTP routes, methods, and
+operation bindings are defined in OpenAPI and enforced at application
+startup.
+
+This package is intended to be copied as a starting point for new
+services via the ``openapi-first`` CLI. It is not part of the
+``openapi_first`` library API surface.
+
+----------------------------------------------------------------------
+Scaffolding via CLI
+----------------------------------------------------------------------
+
+Create a new OpenAPI-first health check service using the bundled
+template:
+
+    openapi-first health_app
+
+Create the service in a custom directory:
+
+    openapi-first health_app my-health-service
+
+List all available application templates:
+
+    openapi-first --list
+
+The CLI copies template files verbatim into the target directory.
+No code is generated or modified beyond the copied scaffold.
+
+----------------------------------------------------------------------
+Client Usage Example
+----------------------------------------------------------------------
+
+The same OpenAPI specification used by the server can be used to
+construct a strict, operationId-driven HTTP client.
+
+Example client call for the ``get_health`` operation:
+
+    from openapi_first.loader import load_openapi
+    from openapi_first.client import OpenAPIClient
+
+    spec = load_openapi("openapi.yaml")
+    client = OpenAPIClient(spec)
+
+    response = client.get_health()
+
+    assert response.status_code == 200
+    assert response.json() == {"status": "ok"}
+
+Client guarantees:
+- One callable per OpenAPI ``operationId``
+- No hardcoded URLs or HTTP methods in user code
+- Path and request parameters must match the OpenAPI specification
+- Invalid or incomplete OpenAPI specs fail at client construction time
+"""

openapi_first/templates/health_app/main.py

@@ -1,3 +1,31 @@
+"""
+Application entry point for an OpenAPI-first FastAPI service.
+
+This module constructs a FastAPI application exclusively from an
+OpenAPI specification and a handler namespace, without using
+decorator-driven routing.
+
+All HTTP routes, methods, and operation bindings are defined in the
+OpenAPI document referenced by ``openapi_path``. Python callables
+defined in the ``routes`` module are bound to OpenAPI operations
+strictly via ``operationId``.
+
+This module contains no routing logic, request handling, or framework
+configuration beyond application assembly.
+
+Design guarantees:
+- OpenAPI is the single source of truth
+- No undocumented routes can exist
+- Every OpenAPI operationId must resolve to exactly one handler
+- All contract violations fail at application startup
+
+This file is intended to be used as the ASGI entry point.
+
+Example:
+    uvicorn main:app
+"""
+
+
 from openapi_first.app import OpenAPIFirstApp
 import routes
 

openapi_first/templates/health_app/routes.py

@@ -1,2 +1,32 @@
+"""
+OpenAPI operation handlers.
+
+This module defines pure Python callables that implement OpenAPI
+operations for this service. Functions in this module are bound to HTTP
+routes exclusively via OpenAPI ``operationId`` values.
+
+No routing decorators, HTTP metadata, or framework-specific logic
+should appear here. All request/response semantics are defined in the
+OpenAPI specification.
+
+This module serves solely as an operationId namespace.
+"""
+
+
 def get_health():
+    """
+    Health check operation handler.
+
+    This function implements the OpenAPI operation identified by
+    ``operationId: get_health``.
+
+    It contains no routing metadata or framework-specific logic.
+    Request binding, HTTP method, and response semantics are defined
+    exclusively by the OpenAPI specification.
+
+    Returns
+    -------
+    dict
+        A minimal liveness payload indicating service health.
+    """
     return {"status": "ok"}