docs(templates): document CRUD and model CRUD apps and expose them in mkdocs

- Add comprehensive module and function docstrings to crud_app and model_app templates
- Document OpenAPI-first guarantees, non-goals, and usage patterns in templates
- Add template-level __init__.py files with CLI and client usage examples
- Update mkdocs.yml to include CRUD and model-based CRUD template documentation
- Ensure template documentation follows strict package-bound mkdocstrings rules

openapi_first/templates/crud_app/__init__.py

@@ -0,0 +1,99 @@
+"""
+OpenAPI-first CRUD application template.
+
+This package contains a complete, minimal example of an OpenAPI-first
+CRUD service built using the ``openapi_first`` library.
+
+The application is assembled exclusively from:
+- an OpenAPI specification (``openapi.yaml``)
+- a handler namespace implementing CRUD operations (``routes``)
+- an in-memory mock data store (``data``)
+
+All HTTP routes, methods, schemas, and operation bindings are defined
+in the OpenAPI specification and enforced at application startup.
+No decorator-driven routing or implicit framework behavior is used.
+
+This template demonstrates:
+- operationId-driven server-side route binding
+- explicit HTTP status code control in handlers
+- operationId-driven client usage against the same OpenAPI contract
+- end-to-end validation using in-memory data and tests
+
+----------------------------------------------------------------------
+Scaffolding via CLI
+----------------------------------------------------------------------
+
+Create a new CRUD example service using the bundled template:
+
+    openapi-first crud_app
+
+Create the service in a custom directory:
+
+    openapi-first crud_app my-crud-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 calls for CRUD operations:
+
+    from openapi_first.loader import load_openapi
+    from openapi_first.client import OpenAPIClient
+
+    spec = load_openapi("openapi.yaml")
+    client = OpenAPIClient(spec)
+
+    # List items
+    response = client.list_items()
+
+    # Get item by ID
+    response = client.get_item(
+        path_params={"item_id": 1}
+    )
+
+    # Create item
+    response = client.create_item(
+        body={"name": "Orange", "price": 0.8}
+    )
+
+    # Update item
+    response = client.update_item(
+        path_params={"item_id": 1},
+        body={"name": "Green Apple", "price": 0.6},
+    )
+
+    # Delete item
+    response = client.delete_item(
+        path_params={"item_id": 1}
+    )
+
+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
+
+----------------------------------------------------------------------
+Non-Goals
+----------------------------------------------------------------------
+
+This template is intentionally minimal and is NOT:
+- production-ready
+- persistent or concurrency-safe
+- a reference architecture for data storage
+
+It exists solely as a copyable example for learning, testing, and
+bootstrapping OpenAPI-first services.
+
+This package is not part of the ``openapi_first`` library API surface.
+"""