fix: apply GSDFC docstring conformance, add minimal annotations to unannotated params (pydoclint zero); refresh lib/MCP docs

.drone.yml

@@ -32,6 +32,26 @@ steps:
           echo "🆕 New version detected: $PACKAGE_NAME==$VERSION"
         fi
 
+  - name: quality-gate
+    image: python:3.13-slim
+    environment:
+      PIP_REPO_URL:
+        from_secret: PIP_REPO_URL
+      PIP_USERNAME:
+        from_secret: PIP_USERNAME
+      PIP_PASSWORD:
+        from_secret: PIP_PASSWORD
+    commands:
+      - pip install --upgrade pip build
+      - |
+        AUTH_URL="https://${PIP_USERNAME}:${PIP_PASSWORD}@$(echo "${PIP_REPO_URL#*://}" | sed 's:/*$::')/simple"
+        pip install --index-url "$AUTH_URL" --extra-index-url https://pypi.org/simple/ -U ".[dev]"
+      - echo "🛡️ Running quality gate..."
+      - python -m black --check .
+      - python -m ruff check .
+      - python -m mypy
+      - python -m pytest
+
   - name: build-package
     image: python:3.13-slim
     commands:

CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+- `py.typed` marker for PEP 561 type information.
+- `.drone.yml` CI with a quality-gate step (black, ruff, mypy, pytest).
+- Canonical `docforge.nav.yml`, generated `mkdocs.yml` and `mcp_docs/` via doc-forge.
+- MIT `LICENSE`.
+
+### Changed
+- Standardized `pyproject.toml` (canonical packaging, lint tool config, extras).
+- `templates/` excluded from black/ruff scans.
+
+### Fixed
+- Stub fixes for typed API surfaces.

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aetoskia Platform
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

docforge.nav.yml

@@ -1,10 +1,13 @@
-home: index.md
+home: lib/index.md
 groups:
   Application Bootstrap:
-    - app.md
+    - lib/app.md
-    - binder.md
+    - lib/binder.md
   Core Utilities:
-    - loader.md
+    - lib/loader.md
-    - errors.md
+    - lib/errors.md
   OpenAPI Client:
-    - client.md
+    - lib/client.md
+icon:
+  logo: material/api
+  repo: fontawesome/brands/github

docs/lib/codegen.md

@@ -0,0 +1,3 @@
+# Codegen
+
+::: openapi_first.codegen

docs/lib/codegen_routes.md

@@ -0,0 +1,3 @@
+# Codegen Routes
+
+::: openapi_first.codegen_routes

docs/lib/index.md

@@ -1,3 +1,4 @@
 # openapi_first
 
 ::: openapi_first
+- [Openapi First](openapi_first/)

docs/lib/openapi_first/app.md

@@ -0,0 +1,3 @@
+# App
+
+::: openapi_first.app

docs/lib/openapi_first/binder.md

@@ -0,0 +1,3 @@
+# Binder
+
+::: openapi_first.binder

docs/lib/openapi_first/cli.md

@@ -0,0 +1,3 @@
+# Cli
+
+::: openapi_first.cli

docs/lib/openapi_first/client.md

@@ -0,0 +1,3 @@
+# Client
+
+::: openapi_first.client

docs/lib/openapi_first/codegen.md

@@ -0,0 +1,3 @@
+# Codegen
+
+::: openapi_first.codegen

docs/lib/openapi_first/codegen_routes.md

@@ -0,0 +1,3 @@
+# Codegen Routes
+
+::: openapi_first.codegen_routes

docs/lib/openapi_first/errors.md

@@ -0,0 +1,3 @@
+# Errors
+
+::: openapi_first.errors

docs/lib/openapi_first/index.md

@@ -0,0 +1,13 @@
+# Openapi First
+
+::: openapi_first
+- [App](app.md)
+- [Binder](binder.md)
+- [Cli](cli.md)
+- [Client](client.md)
+- [Codegen](codegen.md)
+- [Codegen Routes](codegen_routes.md)
+- [Errors](errors.md)
+- [Loader](loader.md)
+- [Security](security.md)
+- [Templates](templates/)

docs/lib/openapi_first/loader.md

@@ -0,0 +1,3 @@
+# Loader
+
+::: openapi_first.loader

docs/lib/openapi_first/security.md

@@ -0,0 +1,3 @@
+# Security
+
+::: openapi_first.security

docs/lib/openapi_first/templates/crud_app/index.md

@@ -0,0 +1,7 @@
+# Crud App
+
+::: openapi_first.templates.crud_app
+- [Data](data.md)
+- [Main](main.md)
+- [Routes](routes.md)
+- [Test Crud App](test_crud_app.md)

docs/lib/openapi_first/templates/health_app/index.md

@@ -0,0 +1,5 @@
+# Health App
+
+::: openapi_first.templates.health_app
+- [Main](main.md)
+- [Routes](routes.md)

docs/lib/openapi_first/templates/index.md

@@ -0,0 +1,7 @@
+# Templates
+
+::: openapi_first.templates
+- [Crud App](crud_app/)
+- [Health App](health_app/)
+- [Model App](model_app/)
+- [Vet App](vet_app/)

docs/lib/openapi_first/templates/model_app/index.md

@@ -0,0 +1,8 @@
+# Model App
+
+::: openapi_first.templates.model_app
+- [Data](data.md)
+- [Main](main.md)
+- [Models](models.md)
+- [Routes](routes.md)
+- [Test Model App](test_model_app.md)

docs/lib/openapi_first/templates/vet_app/data.md

@@ -0,0 +1,3 @@
+# Data
+
+::: openapi_first.templates.vet_app.data

docs/lib/openapi_first/templates/vet_app/index.md

@@ -0,0 +1,9 @@
+# Vet App
+
+::: openapi_first.templates.vet_app
+- [Data](data.md)
+- [Main](main.md)
+- [Models](models.md)
+- [Routes](routes.md)
+- [Sse](sse.md)
+- [Test Vet App](test_vet_app.md)

docs/lib/openapi_first/templates/vet_app/main.md

@@ -0,0 +1,3 @@
+# Main
+
+::: openapi_first.templates.vet_app.main

docs/lib/openapi_first/templates/vet_app/models.md

@@ -0,0 +1,3 @@
+# Models
+
+::: openapi_first.templates.vet_app.models

docs/lib/openapi_first/templates/vet_app/routes.md

@@ -0,0 +1,3 @@
+# Routes
+
+::: openapi_first.templates.vet_app.routes

docs/lib/openapi_first/templates/vet_app/sse.md

@@ -0,0 +1,3 @@
+# Sse
+
+::: openapi_first.templates.vet_app.sse

docs/lib/openapi_first/templates/vet_app/test_vet_app.md

@@ -0,0 +1,3 @@
+# Test Vet App
+
+::: openapi_first.templates.vet_app.test_vet_app

docs/lib/security.md

@@ -0,0 +1,3 @@
+# Security
+
+::: openapi_first.security

docs/lib/templates/crud_app/data.md

@@ -0,0 +1,3 @@
+# Data
+
+::: openapi_first.templates.crud_app.data

docs/lib/templates/crud_app/main.md

@@ -0,0 +1,3 @@
+# Main
+
+::: openapi_first.templates.crud_app.main

docs/lib/templates/crud_app/routes.md

@@ -0,0 +1,3 @@
+# Routes
+
+::: openapi_first.templates.crud_app.routes

docs/lib/templates/crud_app/test_crud_app.md

@@ -0,0 +1,3 @@
+# Test Crud App
+
+::: openapi_first.templates.crud_app.test_crud_app

docs/lib/templates/health_app/main.md

@@ -0,0 +1,3 @@
+# Main
+
+::: openapi_first.templates.health_app.main

docs/lib/templates/health_app/routes.md

@@ -0,0 +1,3 @@
+# Routes
+
+::: openapi_first.templates.health_app.routes

docs/lib/templates/model_app/data.md

@@ -0,0 +1,3 @@
+# Data
+
+::: openapi_first.templates.model_app.data

docs/lib/templates/model_app/main.md

@@ -0,0 +1,3 @@
+# Main
+
+::: openapi_first.templates.model_app.main

docs/lib/templates/model_app/models.md

@@ -0,0 +1,3 @@
+# Models
+
+::: openapi_first.templates.model_app.models

docs/lib/templates/model_app/routes.md

@@ -0,0 +1,3 @@
+# Routes
+
+::: openapi_first.templates.model_app.routes

docs/lib/templates/model_app/test_model_app.md

@@ -0,0 +1,3 @@
+# Test Model App
+
+::: openapi_first.templates.model_app.test_model_app

docs/lib/templates/vet_app/data.md

@@ -0,0 +1,3 @@
+# Data
+
+::: openapi_first.templates.vet_app.data

docs/lib/templates/vet_app/index.md

@@ -0,0 +1,3 @@
+# Vet App
+
+::: openapi_first.templates.vet_app

docs/lib/templates/vet_app/main.md

@@ -0,0 +1,3 @@
+# Main
+
+::: openapi_first.templates.vet_app.main

docs/lib/templates/vet_app/models.md

@@ -0,0 +1,3 @@
+# Models
+
+::: openapi_first.templates.vet_app.models

docs/lib/templates/vet_app/routes.md

@@ -0,0 +1,3 @@
+# Routes
+
+::: openapi_first.templates.vet_app.routes

docs/lib/templates/vet_app/sse.md

@@ -0,0 +1,3 @@
+# Sse
+
+::: openapi_first.templates.vet_app.sse

docs/lib/templates/vet_app/test_vet_app.md

@@ -0,0 +1,3 @@
+# Test Vet App
+
+::: openapi_first.templates.vet_app.test_vet_app

docs/mcp/index.json

@@ -1,6 +1,6 @@
 {
   "project": "openapi_first",
   "type": "docforge-model",
-  "modules_count": 22,
+  "modules_count": 32,
   "source": "docforge"
 }

docs/mcp/modules/openapi_first.app.json

@@ -4,6 +4,27 @@
     "path": "openapi_first.app",
     "docstring": "# Summary\n\nOpenAPI-first application bootstrap for FastAPI.\n\nThis module provides `OpenAPIFirstApp`, a thin but strict abstraction\nthat enforces OpenAPI as the single source of truth for a FastAPI service.\n\nNotes:\n    **Core Principles:**\n\n        - The OpenAPI specification (JSON or YAML) defines the entire API surface.\n        - Every `operationId` in the OpenAPI spec must have a corresponding\n          Python handler function.\n        - Handlers are plain Python callables (no FastAPI decorators).\n        - FastAPI route registration is derived exclusively from the spec.\n        - FastAPI's autogenerated OpenAPI schema is fully overridden.\n\n    **Responsibilities:**\n\n        - Loads and validates an OpenAPI 3.x specification.\n        - Dynamically binds HTTP routes to handler functions using `operationId`.\n        - Registers routes with FastAPI at application startup.\n        - Ensures runtime behavior matches the OpenAPI contract exactly.\n\n    **Constraints:**\n\n        - This module intentionally does NOT:\n            - Generate OpenAPI specs.\n            - Generate client code.\n            - Introduce a new framework or lifecycle.\n            - Alter FastAPI dependency injection semantics.",
     "objects": {
+      "os": {
+        "name": "os",
+        "kind": "alias",
+        "path": "openapi_first.app.os",
+        "signature": "<bound method Alias.signature of Alias('os', 'os')>",
+        "docstring": null
+      },
+      "re": {
+        "name": "re",
+        "kind": "alias",
+        "path": "openapi_first.app.re",
+        "signature": "<bound method Alias.signature of Alias('re', 're')>",
+        "docstring": null
+      },
+      "Any": {
+        "name": "Any",
+        "kind": "alias",
+        "path": "openapi_first.app.Any",
+        "signature": "<bound method Alias.signature of Alias('Any', 'typing.Any')>",
+        "docstring": null
+      },
       "FastAPI": {
         "name": "FastAPI",
         "kind": "alias",
@@ -11,6 +32,13 @@
         "signature": "<bound method Alias.signature of Alias('FastAPI', 'fastapi.FastAPI')>",
         "docstring": null
       },
+      "bind_routes": {
+        "name": "bind_routes",
+        "kind": "function",
+        "path": "openapi_first.app.bind_routes",
+        "signature": "<bound method Alias.signature of Alias('bind_routes', 'openapi_first.binder.bind_routes')>",
+        "docstring": "Bind OpenAPI operations to FastAPI routes.\n\nArgs:\n    app (Any):\n        The FastAPI application instance to which routes will be added.\n    spec (dict):\n        Parsed OpenAPI 3.x specification dictionary.\n    routes_module (Any):\n        Python module containing handler functions. Each handler's name MUST\n        exactly match an OpenAPI `operationId`.\n    security_deps (dict[str, list[Any]] | None):\n        Optional mapping of ``METHOD:/path`` → ``list[Depends(...)]``\n        generated from the spec's ``securitySchemes`` and per-operation\n        ``security`` fields.\n\nRaises:\n    MissingOperationHandler:\n        If an ``operationId`` is missing from the spec or if no corresponding\n        handler function exists in the routes module.\n\nNotes:\n    **Responsibilities:**\n\n        - Iterates through the OpenAPI specification paths and methods.\n        - Resolves each ``operationId`` to a handler function, and registers\n          a corresponding ``APIRoute`` on the FastAPI application.\n        - Injects FastAPI ``Depends()`` for each security requirement found\n          on the operation or inherited from the top-level ``security`` field.\n\n    **Guarantees:**\n\n        - Route registration is deterministic and spec-driven. No route\n          decorators are required or supported. Handler resolution errors\n          surface at application startup."
+      },
       "load_openapi": {
         "name": "load_openapi",
         "kind": "function",
@@ -18,19 +46,26 @@
         "signature": "<bound method Alias.signature of Alias('load_openapi', 'openapi_first.loader.load_openapi')>",
         "docstring": "Load and validate an OpenAPI 3.x specification from disk.\n\nArgs:\n    path (str | Path):\n        Filesystem path to an OpenAPI specification file. Supported\n        extensions: `.json`, `.yaml`, `.yml`.\n\nReturns:\n    dict[str, Any]:\n        Parsed and validated OpenAPI specification.\n\nRaises:\n    OpenAPISpecLoadError:\n        If the file does not exist, cannot be parsed, or fails OpenAPI\n        schema validation.\n\nNotes:\n    **Guarantees:**\n\n        - The specification is parsed based on file extension and validated\n          using a strict OpenAPI schema validator.\n        - Any error results in an immediate exception, preventing\n          application startup."
       },
-      "bind_routes": {
+      "make_security_dependencies": {
-        "name": "bind_routes",
+        "name": "make_security_dependencies",
         "kind": "function",
-        "path": "openapi_first.app.bind_routes",
+        "path": "openapi_first.app.make_security_dependencies",
-        "signature": "<bound method Alias.signature of Alias('bind_routes', 'openapi_first.binder.bind_routes')>",
+        "signature": "<bound method Alias.signature of Alias('make_security_dependencies', 'openapi_first.security.make_security_dependencies')>",
-        "docstring": "Bind OpenAPI operations to FastAPI routes.\n\nArgs:\n    app (fastapi.FastAPI):\n        The FastAPI application instance to which routes will be added.\n    spec (dict):\n        Parsed OpenAPI 3.x specification dictionary.\n    routes_module (module):\n        Python module containing handler functions. Each handler's name MUST\n        exactly match an OpenAPI `operationId`.\n\nRaises:\n    MissingOperationHandler:\n        If an `operationId` is missing from the spec or if no corresponding\n        handler function exists in the routes module.\n\nNotes:\n    **Responsibilities:**\n\n        - Iterates through the OpenAPI specification paths and methods.\n        - Resolves each `operationId` to a handler function, and registers\n          a corresponding `APIRoute` on the FastAPI application.\n\n    **Guarantees:**\n\n        - Route registration is deterministic and spec-driven. No route\n          decorators are required or supported. Handler resolution errors\n          surface at application startup."
+        "docstring": "Build a mapping of ``METHOD:/path`` → list of ``Depends(...)``.\n\nThe effective security for each operation is resolved by:\n\n1. Using the operation-level ``security`` field if present.\n2. Falling back to the top-level ``security`` field.\n3. An empty list means *no auth required* for that operation."
+      },
+      "parse_security_schemes": {
+        "name": "parse_security_schemes",
+        "kind": "function",
+        "path": "openapi_first.app.parse_security_schemes",
+        "signature": "<bound method Alias.signature of Alias('parse_security_schemes', 'openapi_first.security.parse_security_schemes')>",
+        "docstring": "Extract and resolve environment variables in security schemes."
       },
       "OpenAPIFirstApp": {
         "name": "OpenAPIFirstApp",
         "kind": "class",
         "path": "openapi_first.app.OpenAPIFirstApp",
-        "signature": "<bound method Class.signature of Class('OpenAPIFirstApp', 41, 115)>",
+        "signature": "<bound method Class.signature of Class('OpenAPIFirstApp', 68, 151)>",
-        "docstring": "FastAPI application enforcing OpenAPI-first design.\n\nNotes:\n    **Responsibilities:**\n\n        - `OpenAPIFirstApp` subclasses `FastAPI` and replaces manual route\n          registration with OpenAPI-driven binding.\n        - All routes are derived from the provided OpenAPI specification,\n          and each `operationId` is mapped to a Python function in the\n          supplied routes module.\n\n    **Guarantees:**\n\n        - No route can exist without an OpenAPI declaration.\n        - No OpenAPI operation can exist without a handler.\n        - Swagger UI and `/openapi.json` always reflect the provided spec.\n        - Handler functions remain framework-agnostic and testable.\n\nExample:\n    ```python\n    from openapi_first import OpenAPIFirstApp\n    import app.routes as routes\n\n    app = OpenAPIFirstApp(\n        openapi_path=\"app/openapi.json\",\n        routes_module=routes,\n        title=\"Example Service\",\n    )\n    ```",
+        "docstring": "FastAPI application enforcing OpenAPI-first design.\n\nNotes:\n    **Responsibilities:**\n\n        - `OpenAPIFirstApp` subclasses `FastAPI` and replaces manual route\n          registration with OpenAPI-driven binding.\n        - All routes are derived from the provided OpenAPI specification,\n          and each ``operationId`` is mapped to a Python function in the\n          supplied routes module.\n        - Auth dependencies are auto-injected from the spec's\n          ``securitySchemes`` and per-operation ``security`` fields.\n\n    **Guarantees:**\n\n        - No route can exist without an OpenAPI declaration.\n        - No OpenAPI operation can exist without a handler.\n        - Swagger UI and ``/openapi.json`` always reflect the provided spec.\n        - Handler functions remain framework-agnostic and testable.\n        - Auth enforcement is driven entirely by the spec — no manual\n          middleware or decorators required.\n\nExample:\n    ```python\n    from openapi_first import OpenAPIFirstApp\n    import app.routes as routes\n\n    app = OpenAPIFirstApp(\n        openapi_path=\"app/openapi.json\",\n        routes_module=routes,\n        title=\"Example Service\",\n    )\n    ```",
         "members": {
           "openapi": {
             "name": "openapi",
@@ -40,13 +75,6 @@
             "docstring": null
           }
         }
-      },
-      "Any": {
-        "name": "Any",
-        "kind": "alias",
-        "path": "openapi_first.app.Any",
-        "signature": "<bound method Alias.signature of Alias('Any', 'typing.Any')>",
-        "docstring": null
       }
     }
   }

docs/mcp/modules/openapi_first.binder.json

@@ -4,6 +4,13 @@
     "path": "openapi_first.binder",
     "docstring": "# Summary\n\nOpenAPI-driven route binding for FastAPI.\n\nThis module is responsible for translating an OpenAPI 3.x specification\ninto concrete FastAPI routes. It enforces a strict one-to-one mapping\nbetween OpenAPI operations and Python handler functions using `operationId`.\n\nNotes:\n    **Core Responsibility:**\n\n        - Read path + method definitions from an OpenAPI specification.\n        - Resolve each `operationId` to a Python callable.\n        - Register routes with FastAPI using `APIRoute`.\n        - Fail fast when contract violations are detected.\n\n    **Design Constraints:**\n\n        - All routes MUST be declared in the OpenAPI specification.\n        - All OpenAPI operations MUST define an `operationId`.\n        - Every `operationId` MUST resolve to a handler function.\n        - Handlers are plain Python callables (no decorators required).\n        - No implicit route creation or inference is allowed.\n\n    **Constraints:**\n\n        - This module intentionally does NOT:\n            - Perform request or response validation.\n            - Generate Pydantic models.\n            - Modify FastAPI dependency injection.\n            - Interpret OpenAPI semantics beyond routing metadata.",
     "objects": {
+      "Any": {
+        "name": "Any",
+        "kind": "alias",
+        "path": "openapi_first.binder.Any",
+        "signature": "<bound method Alias.signature of Alias('Any', 'typing.Any')>",
+        "docstring": null
+      },
       "APIRoute": {
         "name": "APIRoute",
         "kind": "alias",
@@ -22,22 +29,8 @@
         "name": "bind_routes",
         "kind": "function",
         "path": "openapi_first.binder.bind_routes",
-        "signature": "<bound method Function.signature of Function('bind_routes', 40, 100)>",
+        "signature": "<bound method Function.signature of Function('bind_routes', 42, 124)>",
-        "docstring": "Bind OpenAPI operations to FastAPI routes.\n\nArgs:\n    app (fastapi.FastAPI):\n        The FastAPI application instance to which routes will be added.\n    spec (dict):\n        Parsed OpenAPI 3.x specification dictionary.\n    routes_module (module):\n        Python module containing handler functions. Each handler's name MUST\n        exactly match an OpenAPI `operationId`.\n\nRaises:\n    MissingOperationHandler:\n        If an `operationId` is missing from the spec or if no corresponding\n        handler function exists in the routes module.\n\nNotes:\n    **Responsibilities:**\n\n        - Iterates through the OpenAPI specification paths and methods.\n        - Resolves each `operationId` to a handler function, and registers\n          a corresponding `APIRoute` on the FastAPI application.\n\n    **Guarantees:**\n\n        - Route registration is deterministic and spec-driven. No route\n          decorators are required or supported. Handler resolution errors\n          surface at application startup."
+        "docstring": "Bind OpenAPI operations to FastAPI routes.\n\nArgs:\n    app (Any):\n        The FastAPI application instance to which routes will be added.\n    spec (dict):\n        Parsed OpenAPI 3.x specification dictionary.\n    routes_module (Any):\n        Python module containing handler functions. Each handler's name MUST\n        exactly match an OpenAPI `operationId`.\n    security_deps (dict[str, list[Any]] | None):\n        Optional mapping of ``METHOD:/path`` → ``list[Depends(...)]``\n        generated from the spec's ``securitySchemes`` and per-operation\n        ``security`` fields.\n\nRaises:\n    MissingOperationHandler:\n        If an ``operationId`` is missing from the spec or if no corresponding\n        handler function exists in the routes module.\n\nNotes:\n    **Responsibilities:**\n\n        - Iterates through the OpenAPI specification paths and methods.\n        - Resolves each ``operationId`` to a handler function, and registers\n          a corresponding ``APIRoute`` on the FastAPI application.\n        - Injects FastAPI ``Depends()`` for each security requirement found\n          on the operation or inherited from the top-level ``security`` field.\n\n    **Guarantees:**\n\n        - Route registration is deterministic and spec-driven. No route\n          decorators are required or supported. Handler resolution errors\n          surface at application startup."
-      },
-      "Any": {
-        "name": "Any",
-        "kind": "alias",
-        "path": "openapi_first.binder.Any",
-        "signature": "<bound method Alias.signature of Alias('Any', 'typing.Any')>",
-        "docstring": null
-      },
-      "Dict": {
-        "name": "Dict",
-        "kind": "alias",
-        "path": "openapi_first.binder.Dict",
-        "signature": "<bound method Alias.signature of Alias('Dict', 'typing.Dict')>",
-        "docstring": null
       },
       "FastAPI": {
         "name": "FastAPI",

docs/mcp/modules/openapi_first.cli.json

@@ -2,7 +2,7 @@
   "module": "openapi_first.cli",
   "content": {
     "path": "openapi_first.cli",
-    "docstring": "Command-line interface for FastAPI OpenAPI-first scaffolding utilities.\n\n---\n\n## Summary\n\nThis CLI bootstraps OpenAPI-first FastAPI applications from versioned,\nbundled templates packaged with the library.",
+    "docstring": "# Summary\n\nCommand-line interface for FastAPI OpenAPI-first scaffolding utilities.\n\nThis CLI bootstraps OpenAPI-first FastAPI applications from versioned,\nbundled templates packaged with the library.",
     "objects": {
       "argparse": {
         "name": "argparse",
@@ -18,13 +18,6 @@
         "signature": "<bound method Alias.signature of Alias('shutil', 'shutil')>",
         "docstring": null
       },
-      "Path": {
-        "name": "Path",
-        "kind": "alias",
-        "path": "openapi_first.cli.Path",
-        "signature": "<bound method Alias.signature of Alias('Path', 'pathlib.Path')>",
-        "docstring": null
-      },
       "resources": {
         "name": "resources",
         "kind": "alias",
@@ -32,6 +25,13 @@
         "signature": "<bound method Alias.signature of Alias('resources', 'importlib.resources')>",
         "docstring": null
       },
+      "Path": {
+        "name": "Path",
+        "kind": "alias",
+        "path": "openapi_first.cli.Path",
+        "signature": "<bound method Alias.signature of Alias('Path', 'pathlib.Path')>",
+        "docstring": null
+      },
       "DEFAULT_TEMPLATE": {
         "name": "DEFAULT_TEMPLATE",
         "kind": "attribute",
@@ -43,21 +43,21 @@
         "name": "available_templates",
         "kind": "function",
         "path": "openapi_first.cli.available_templates",
-        "signature": "<bound method Function.signature of Function('available_templates', 21, 34)>",
+        "signature": "<bound method Function.signature of Function('available_templates', 18, 31)>",
         "docstring": "Return a list of available application templates.\n\nReturns:\n    list[str]:\n        Sorted list of template names found in the internal templates directory."
       },
       "copy_template": {
         "name": "copy_template",
         "kind": "function",
         "path": "openapi_first.cli.copy_template",
-        "signature": "<bound method Function.signature of Function('copy_template', 37, 64)>",
+        "signature": "<bound method Function.signature of Function('copy_template', 34, 62)>",
         "docstring": "Copy a bundled OpenAPI-first application template into a directory.\n\nArgs:\n    template (str):\n        Name of the template to copy.\n    target_dir (Path):\n        Filesystem path where the template should be copied.\n\nRaises:\n    FileNotFoundError:\n        If the requested template does not exist."
       },
       "main": {
         "name": "main",
         "kind": "function",
         "path": "openapi_first.cli.main",
-        "signature": "<bound method Function.signature of Function('main', 67, 103)>",
+        "signature": "<bound method Function.signature of Function('main', 65, 194)>",
         "docstring": null
       }
     }

docs/mcp/modules/openapi_first.client.json

@@ -4,6 +4,13 @@
     "path": "openapi_first.client",
     "docstring": "# Summary\n\nOpenAPI-first HTTP client for contract-driven services.\n\nThis module provides `OpenAPIClient`, a thin, strict HTTP client that\nderives all callable operations directly from an OpenAPI 3.x specification.\n\nIt is the client counterpart to `OpenAPIFirstApp`.\n\nNotes:\n    **Core Principles:**\n\n        - The OpenAPI specification is the single source of truth\n        - Each operationId becomes a callable Python method\n        - No implicit schema mutation or inference\n        - No code generation step\n        - Minimal abstraction over httpx\n\n    **Responsibilities:**\n\n        - Parses an OpenAPI 3.x specification\n        - Dynamically creates one callable per operationId\n        - Enforces presence of servers, paths, and operationId\n        - Formats path parameters safely\n        - Handles JSON request bodies explicitly\n        - Returns raw `httpx.Response` objects\n\n    **Constraints:**\n\n        - This module intentionally does NOT: Generate client code, validate request/response schemas, deserialize responses, retry requests, implement authentication helpers, or assume non-2xx responses are failures.",
     "objects": {
+      "Callable": {
+        "name": "Callable",
+        "kind": "alias",
+        "path": "openapi_first.client.Callable",
+        "signature": "<bound method Alias.signature of Alias('Callable', 'collections.abc.Callable')>",
+        "docstring": null
+      },
       "Any": {
         "name": "Any",
         "kind": "alias",
@@ -11,27 +18,6 @@
         "signature": "<bound method Alias.signature of Alias('Any', 'typing.Any')>",
         "docstring": null
       },
-      "Callable": {
-        "name": "Callable",
-        "kind": "alias",
-        "path": "openapi_first.client.Callable",
-        "signature": "<bound method Alias.signature of Alias('Callable', 'typing.Callable')>",
-        "docstring": null
-      },
-      "Dict": {
-        "name": "Dict",
-        "kind": "alias",
-        "path": "openapi_first.client.Dict",
-        "signature": "<bound method Alias.signature of Alias('Dict', 'typing.Dict')>",
-        "docstring": null
-      },
-      "Optional": {
-        "name": "Optional",
-        "kind": "alias",
-        "path": "openapi_first.client.Optional",
-        "signature": "<bound method Alias.signature of Alias('Optional', 'typing.Optional')>",
-        "docstring": null
-      },
       "urljoin": {
         "name": "urljoin",
         "kind": "alias",
@@ -57,14 +43,14 @@
         "name": "OpenAPIClientError",
         "kind": "class",
         "path": "openapi_first.client.OpenAPIClientError",
-        "signature": "<bound method Class.signature of Class('OpenAPIClientError', 42, 45)>",
+        "signature": "<bound method Class.signature of Class('OpenAPIClientError', 43, 46)>",
         "docstring": "Raised when an OpenAPI client operation fails."
       },
       "OpenAPIClient": {
         "name": "OpenAPIClient",
         "kind": "class",
         "path": "openapi_first.client.OpenAPIClient",
-        "signature": "<bound method Class.signature of Class('OpenAPIClient', 48, 257)>",
+        "signature": "<bound method Class.signature of Class('OpenAPIClient', 49, 262)>",
         "docstring": "OpenAPI-first HTTP client (`httpx`-based).\n\nNotes:\n    **Responsibilities:**\n\n        - This client derives all callable methods directly from an\n          OpenAPI 3.x specification. Each `operationId` becomes a method\n          on the client instance.\n\n    **Guarantees:**\n\n        - One callable per `operationId`.\n        - Explicit parameters (path, query, headers, body).\n        - No implicit schema inference or mutation.\n        - Returns raw `httpx.Response` objects.\n        - No response validation or deserialization.\n\nExample:\n    ```python\n    from openapi_first import loader, client\n\n    spec = loader.load_openapi(\"openapi.yaml\")\n\n    api = client.OpenAPIClient(\n        spec=spec,\n        base_url=\"http://localhost:8000\",\n    )\n\n    # Call operationId: getUser\n    response = api.getUser(\n        path_params={\"user_id\": 123}\n    )\n\n    print(response.status_code)\n    print(response.json())\n    ```",
         "members": {
           "spec": {
@@ -92,7 +78,7 @@
             "name": "operations",
             "kind": "function",
             "path": "openapi_first.client.OpenAPIClient.operations",
-            "signature": "<bound method Function.signature of Function('operations', 126, 127)>",
+            "signature": "<bound method Function.signature of Function('operations', 127, 128)>",
             "docstring": null
           }
         }

docs/mcp/modules/openapi_first.codegen.json

@@ -0,0 +1,51 @@
+{
+  "module": "openapi_first.codegen",
+  "content": {
+    "path": "openapi_first.codegen",
+    "docstring": "# Summary\n\nCore logic for generating Python source code from OpenAPI specifications.\n\nThis module provides reusable utilities for code generation, specifically\ngenerating Pydantic models and route handler stubs from OpenAPI 3.x schema\ndefinitions.",
+    "objects": {
+      "Path": {
+        "name": "Path",
+        "kind": "alias",
+        "path": "openapi_first.codegen.Path",
+        "signature": "<bound method Alias.signature of Alias('Path', 'pathlib.Path')>",
+        "docstring": null
+      },
+      "InputFileType": {
+        "name": "InputFileType",
+        "kind": "alias",
+        "path": "openapi_first.codegen.InputFileType",
+        "signature": "<bound method Alias.signature of Alias('InputFileType', 'datamodel_code_generator.InputFileType')>",
+        "docstring": null
+      },
+      "PythonVersion": {
+        "name": "PythonVersion",
+        "kind": "alias",
+        "path": "openapi_first.codegen.PythonVersion",
+        "signature": "<bound method Alias.signature of Alias('PythonVersion', 'datamodel_code_generator.PythonVersion')>",
+        "docstring": null
+      },
+      "generate": {
+        "name": "generate",
+        "kind": "alias",
+        "path": "openapi_first.codegen.generate",
+        "signature": "<bound method Alias.signature of Alias('generate', 'datamodel_code_generator.generate')>",
+        "docstring": null
+      },
+      "generate_routes": {
+        "name": "generate_routes",
+        "kind": "function",
+        "path": "openapi_first.codegen.generate_routes",
+        "signature": "<bound method Alias.signature of Alias('generate_routes', 'openapi_first.codegen_routes.generate_routes')>",
+        "docstring": "Generate route handler stubs from an OpenAPI specification.\n\nCreates one ``<resource>.py`` file per resource in *output_dir*.\nResources are derived from the first path segment (e.g. ``/pets``\nand ``/pets/{id}`` both group under ``pets``).\n\nArgs:\n    spec_path (Path):\n        Path to the OpenAPI specification file (YAML or JSON).\n    output_dir (Path):\n        Directory where the generated route files are written.\n        Created automatically if it does not exist.\n    use_models (bool, optional):\n        If ``True``, import Pydantic models from *models_module*\n        for request-body schemas referenced via ``$ref``.\n    models_module (str, optional):\n        Dotted Python module path from which to import models\n        (e.g. ``\"models\"``, ``\"app.models\"``).\n\nReturns:\n    list[Path]:\n        Absolute paths of every generated route file.\n\nRaises:\n    OpenAPISpecLoadError:\n        If the spec cannot be loaded or validated.\n    ValueError:\n        If any operation is missing ``operationId``."
+      },
+      "generate_models": {
+        "name": "generate_models",
+        "kind": "function",
+        "path": "openapi_first.codegen.generate_models",
+        "signature": "<bound method Function.signature of Function('generate_models', 22, 51)>",
+        "docstring": "Generate Pydantic models from an OpenAPI specification.\n\nArgs:\n    spec_path (Path):\n        Path to the OpenAPI specification file (YAML or JSON).\n    output_path (Path):\n        Path where the generated Python code should be written.\n    pydantic_version (int, optional):\n        The Pydantic version to target (1 or 2). Defaults to 2.\n\nNotes:\n    **Reusability:**\n        This function is designed to be used by the CLI and can be\n        exposed as an MCP tool without modification."
+      }
+    }
+  }
+}

docs/mcp/modules/openapi_first.codegen_routes.json

@@ -0,0 +1,37 @@
+{
+  "module": "openapi_first.codegen_routes",
+  "content": {
+    "path": "openapi_first.codegen_routes",
+    "docstring": "# Summary\n\nRoute handler code generation from OpenAPI specifications.\n\nThis module generates Python route handler stubs from an OpenAPI 3.x\nspecification. Each resource (derived from the first path segment)\ngets its own file under the output directory. Every OpenAPI operation\nmust define an ``operationId``, which becomes the handler function name.\n\nNotes:\n    **Design constraints:**\n\n        - ``operationId`` is required on every operation (matching\n          ``binder.bind_routes``).\n        - Handlers are stubs raising ``NotImplementedError``.\n        - Sub-resources (e.g. ``/pets/{id}/photo``) are grouped with their\n          parent resource (``pets``).\n        - Parameter types and defaults are inferred from the spec.\n        - ``response: Response`` is injected for non-200 success codes.",
+    "objects": {
+      "Path": {
+        "name": "Path",
+        "kind": "alias",
+        "path": "openapi_first.codegen_routes.Path",
+        "signature": "<bound method Alias.signature of Alias('Path', 'pathlib.Path')>",
+        "docstring": null
+      },
+      "Any": {
+        "name": "Any",
+        "kind": "alias",
+        "path": "openapi_first.codegen_routes.Any",
+        "signature": "<bound method Alias.signature of Alias('Any', 'typing.Any')>",
+        "docstring": null
+      },
+      "load_openapi": {
+        "name": "load_openapi",
+        "kind": "function",
+        "path": "openapi_first.codegen_routes.load_openapi",
+        "signature": "<bound method Alias.signature of Alias('load_openapi', 'openapi_first.loader.load_openapi')>",
+        "docstring": "Load and validate an OpenAPI 3.x specification from disk.\n\nArgs:\n    path (str | Path):\n        Filesystem path to an OpenAPI specification file. Supported\n        extensions: `.json`, `.yaml`, `.yml`.\n\nReturns:\n    dict[str, Any]:\n        Parsed and validated OpenAPI specification.\n\nRaises:\n    OpenAPISpecLoadError:\n        If the file does not exist, cannot be parsed, or fails OpenAPI\n        schema validation.\n\nNotes:\n    **Guarantees:**\n\n        - The specification is parsed based on file extension and validated\n          using a strict OpenAPI schema validator.\n        - Any error results in an immediate exception, preventing\n          application startup."
+      },
+      "generate_routes": {
+        "name": "generate_routes",
+        "kind": "function",
+        "path": "openapi_first.codegen_routes.generate_routes",
+        "signature": "<bound method Function.signature of Function('generate_routes', 29, 104)>",
+        "docstring": "Generate route handler stubs from an OpenAPI specification.\n\nCreates one ``<resource>.py`` file per resource in *output_dir*.\nResources are derived from the first path segment (e.g. ``/pets``\nand ``/pets/{id}`` both group under ``pets``).\n\nArgs:\n    spec_path (Path):\n        Path to the OpenAPI specification file (YAML or JSON).\n    output_dir (Path):\n        Directory where the generated route files are written.\n        Created automatically if it does not exist.\n    use_models (bool, optional):\n        If ``True``, import Pydantic models from *models_module*\n        for request-body schemas referenced via ``$ref``.\n    models_module (str, optional):\n        Dotted Python module path from which to import models\n        (e.g. ``\"models\"``, ``\"app.models\"``).\n\nReturns:\n    list[Path]:\n        Absolute paths of every generated route file.\n\nRaises:\n    OpenAPISpecLoadError:\n        If the spec cannot be loaded or validated.\n    ValueError:\n        If any operation is missing ``operationId``."
+      }
+    }
+  }
+}

docs/mcp/modules/openapi_first.errors.json

@@ -8,22 +8,15 @@
         "name": "OpenAPIFirstError",
         "kind": "class",
         "path": "openapi_first.errors.OpenAPIFirstError",
-        "signature": "<bound method Class.signature of Class('OpenAPIFirstError', 21, 34)>",
+        "signature": "<bound method Class.signature of Class('OpenAPIFirstError', 22, 36)>",
         "docstring": "Base exception for all OpenAPI-first enforcement errors.\n\nNotes:\n    **Responsibilities:**\n\n        - This exception exists to allow callers, test suites, and CI\n          pipelines to catch and distinguish OpenAPI contract violations\n          from unrelated runtime errors.\n        - All exceptions raised by the OpenAPI-first core should inherit\n          from this type."
       },
       "MissingOperationHandler": {
         "name": "MissingOperationHandler",
         "kind": "class",
         "path": "openapi_first.errors.MissingOperationHandler",
-        "signature": "<bound method Class.signature of Class('MissingOperationHandler', 37, 78)>",
+        "signature": "<bound method Class.signature of Class('MissingOperationHandler', 39, 77)>",
         "docstring": "Raised when an OpenAPI operation cannot be resolved to a handler.\n\nNotes:\n    **Scenarios:**\n\n        - An OpenAPI operation does not define an `operationId`.\n        - An `operationId` is defined but no matching function exists in\n          the provided routes module.\n\n    **Guarantees:**\n\n        - This represents a violation of the OpenAPI-first contract and\n          indicates that the specification and implementation are out of\n          sync."
-      },
-      "Optional": {
-        "name": "Optional",
-        "kind": "alias",
-        "path": "openapi_first.errors.Optional",
-        "signature": "<bound method Alias.signature of Alias('Optional', 'typing.Optional')>",
-        "docstring": null
       }
     }
   }

docs/mcp/modules/openapi_first.loader.json

@@ -50,29 +50,15 @@
         "name": "OpenAPISpecLoadError",
         "kind": "class",
         "path": "openapi_first.loader.OpenAPISpecLoadError",
-        "signature": "<bound method Class.signature of Class('OpenAPISpecLoadError', 39, 49)>",
+        "signature": "<bound method Class.signature of Class('OpenAPISpecLoadError', 39, 50)>",
         "docstring": "Raised when an OpenAPI specification cannot be loaded or validated.\n\nNotes:\n    **Guarantees:**\n\n        - This error indicates that the OpenAPI document is unreadable,\n          malformed, or violates the OpenAPI 3.x specification."
       },
       "load_openapi": {
         "name": "load_openapi",
         "kind": "function",
         "path": "openapi_first.loader.load_openapi",
-        "signature": "<bound method Function.signature of Function('load_openapi', 52, 109)>",
+        "signature": "<bound method Function.signature of Function('load_openapi', 53, 110)>",
         "docstring": "Load and validate an OpenAPI 3.x specification from disk.\n\nArgs:\n    path (str | Path):\n        Filesystem path to an OpenAPI specification file. Supported\n        extensions: `.json`, `.yaml`, `.yml`.\n\nReturns:\n    dict[str, Any]:\n        Parsed and validated OpenAPI specification.\n\nRaises:\n    OpenAPISpecLoadError:\n        If the file does not exist, cannot be parsed, or fails OpenAPI\n        schema validation.\n\nNotes:\n    **Guarantees:**\n\n        - The specification is parsed based on file extension and validated\n          using a strict OpenAPI schema validator.\n        - Any error results in an immediate exception, preventing\n          application startup."
-      },
-      "Dict": {
-        "name": "Dict",
-        "kind": "alias",
-        "path": "openapi_first.loader.Dict",
-        "signature": "<bound method Alias.signature of Alias('Dict', 'typing.Dict')>",
-        "docstring": null
-      },
-      "Union": {
-        "name": "Union",
-        "kind": "alias",
-        "path": "openapi_first.loader.Union",
-        "signature": "<bound method Alias.signature of Alias('Union', 'typing.Union')>",
-        "docstring": null
       }
     }
   }

docs/mcp/modules/openapi_first.security.json

@@ -0,0 +1,93 @@
+{
+  "module": "openapi_first.security",
+  "content": {
+    "path": "openapi_first.security",
+    "docstring": "# Summary\n\nOpenAPI security scheme parsing and auto-generated auth dependencies.\n\nThis module reads `securitySchemes` and per-operation `security` from an\nOpenAPI spec, resolves `{ENV_VAR}` placeholders in `x-` extension fields,\nand generates FastAPI dependencies for token validation (e.g., Bearer JWT\nintrospection).",
+    "objects": {
+      "os": {
+        "name": "os",
+        "kind": "alias",
+        "path": "openapi_first.security.os",
+        "signature": "<bound method Alias.signature of Alias('os', 'os')>",
+        "docstring": null
+      },
+      "re": {
+        "name": "re",
+        "kind": "alias",
+        "path": "openapi_first.security.re",
+        "signature": "<bound method Alias.signature of Alias('re', 're')>",
+        "docstring": null
+      },
+      "Callable": {
+        "name": "Callable",
+        "kind": "alias",
+        "path": "openapi_first.security.Callable",
+        "signature": "<bound method Alias.signature of Alias('Callable', 'collections.abc.Callable')>",
+        "docstring": null
+      },
+      "Any": {
+        "name": "Any",
+        "kind": "alias",
+        "path": "openapi_first.security.Any",
+        "signature": "<bound method Alias.signature of Alias('Any', 'typing.Any')>",
+        "docstring": null
+      },
+      "httpx": {
+        "name": "httpx",
+        "kind": "alias",
+        "path": "openapi_first.security.httpx",
+        "signature": "<bound method Alias.signature of Alias('httpx', 'httpx')>",
+        "docstring": null
+      },
+      "Depends": {
+        "name": "Depends",
+        "kind": "alias",
+        "path": "openapi_first.security.Depends",
+        "signature": "<bound method Alias.signature of Alias('Depends', 'fastapi.Depends')>",
+        "docstring": null
+      },
+      "HTTPException": {
+        "name": "HTTPException",
+        "kind": "alias",
+        "path": "openapi_first.security.HTTPException",
+        "signature": "<bound method Alias.signature of Alias('HTTPException', 'fastapi.HTTPException')>",
+        "docstring": null
+      },
+      "Request": {
+        "name": "Request",
+        "kind": "alias",
+        "path": "openapi_first.security.Request",
+        "signature": "<bound method Alias.signature of Alias('Request', 'fastapi.Request')>",
+        "docstring": null
+      },
+      "HTTPAuthorizationCredentials": {
+        "name": "HTTPAuthorizationCredentials",
+        "kind": "alias",
+        "path": "openapi_first.security.HTTPAuthorizationCredentials",
+        "signature": "<bound method Alias.signature of Alias('HTTPAuthorizationCredentials', 'fastapi.security.HTTPAuthorizationCredentials')>",
+        "docstring": null
+      },
+      "HTTPBearer": {
+        "name": "HTTPBearer",
+        "kind": "alias",
+        "path": "openapi_first.security.HTTPBearer",
+        "signature": "<bound method Alias.signature of Alias('HTTPBearer', 'fastapi.security.HTTPBearer')>",
+        "docstring": null
+      },
+      "parse_security_schemes": {
+        "name": "parse_security_schemes",
+        "kind": "function",
+        "path": "openapi_first.security.parse_security_schemes",
+        "signature": "<bound method Function.signature of Function('parse_security_schemes', 46, 49)>",
+        "docstring": "Extract and resolve environment variables in security schemes."
+      },
+      "make_security_dependencies": {
+        "name": "make_security_dependencies",
+        "kind": "function",
+        "path": "openapi_first.security.make_security_dependencies",
+        "signature": "<bound method Function.signature of Function('make_security_dependencies', 116, 153)>",
+        "docstring": "Build a mapping of ``METHOD:/path`` → list of ``Depends(...)``.\n\nThe effective security for each operation is resolved by:\n\n1. Using the operation-level ``security`` field if present.\n2. Falling back to the top-level ``security`` field.\n3. An empty list means *no auth required* for that operation."
+      }
+    }
+  }
+}

docs/mcp/modules/openapi_first.templates.crud_app.json

@@ -67,7 +67,7 @@
             "kind": "class",
             "path": "openapi_first.templates.crud_app.main.OpenAPIFirstApp",
             "signature": "<bound method Alias.signature of Alias('OpenAPIFirstApp', 'openapi_first.app.OpenAPIFirstApp')>",
-            "docstring": "FastAPI application enforcing OpenAPI-first design.\n\nNotes:\n    **Responsibilities:**\n\n        - `OpenAPIFirstApp` subclasses `FastAPI` and replaces manual route\n          registration with OpenAPI-driven binding.\n        - All routes are derived from the provided OpenAPI specification,\n          and each `operationId` is mapped to a Python function in the\n          supplied routes module.\n\n    **Guarantees:**\n\n        - No route can exist without an OpenAPI declaration.\n        - No OpenAPI operation can exist without a handler.\n        - Swagger UI and `/openapi.json` always reflect the provided spec.\n        - Handler functions remain framework-agnostic and testable.\n\nExample:\n    ```python\n    from openapi_first import OpenAPIFirstApp\n    import app.routes as routes\n\n    app = OpenAPIFirstApp(\n        openapi_path=\"app/openapi.json\",\n        routes_module=routes,\n        title=\"Example Service\",\n    )\n    ```",
+            "docstring": "FastAPI application enforcing OpenAPI-first design.\n\nNotes:\n    **Responsibilities:**\n\n        - `OpenAPIFirstApp` subclasses `FastAPI` and replaces manual route\n          registration with OpenAPI-driven binding.\n        - All routes are derived from the provided OpenAPI specification,\n          and each ``operationId`` is mapped to a Python function in the\n          supplied routes module.\n        - Auth dependencies are auto-injected from the spec's\n          ``securitySchemes`` and per-operation ``security`` fields.\n\n    **Guarantees:**\n\n        - No route can exist without an OpenAPI declaration.\n        - No OpenAPI operation can exist without a handler.\n        - Swagger UI and ``/openapi.json`` always reflect the provided spec.\n        - Handler functions remain framework-agnostic and testable.\n        - Auth enforcement is driven entirely by the spec — no manual\n          middleware or decorators required.\n\nExample:\n    ```python\n    from openapi_first import OpenAPIFirstApp\n    import app.routes as routes\n\n    app = OpenAPIFirstApp(\n        openapi_path=\"app/openapi.json\",\n        routes_module=routes,\n        title=\"Example Service\",\n    )\n    ```",
             "members": {
               "openapi": {
                 "name": "openapi",

docs/mcp/modules/openapi_first.templates.crud_app.main.json

@@ -9,7 +9,7 @@
         "kind": "class",
         "path": "openapi_first.templates.crud_app.main.OpenAPIFirstApp",
         "signature": "<bound method Alias.signature of Alias('OpenAPIFirstApp', 'openapi_first.app.OpenAPIFirstApp')>",
-        "docstring": "FastAPI application enforcing OpenAPI-first design.\n\nNotes:\n    **Responsibilities:**\n\n        - `OpenAPIFirstApp` subclasses `FastAPI` and replaces manual route\n          registration with OpenAPI-driven binding.\n        - All routes are derived from the provided OpenAPI specification,\n          and each `operationId` is mapped to a Python function in the\n          supplied routes module.\n\n    **Guarantees:**\n\n        - No route can exist without an OpenAPI declaration.\n        - No OpenAPI operation can exist without a handler.\n        - Swagger UI and `/openapi.json` always reflect the provided spec.\n        - Handler functions remain framework-agnostic and testable.\n\nExample:\n    ```python\n    from openapi_first import OpenAPIFirstApp\n    import app.routes as routes\n\n    app = OpenAPIFirstApp(\n        openapi_path=\"app/openapi.json\",\n        routes_module=routes,\n        title=\"Example Service\",\n    )\n    ```",
+        "docstring": "FastAPI application enforcing OpenAPI-first design.\n\nNotes:\n    **Responsibilities:**\n\n        - `OpenAPIFirstApp` subclasses `FastAPI` and replaces manual route\n          registration with OpenAPI-driven binding.\n        - All routes are derived from the provided OpenAPI specification,\n          and each ``operationId`` is mapped to a Python function in the\n          supplied routes module.\n        - Auth dependencies are auto-injected from the spec's\n          ``securitySchemes`` and per-operation ``security`` fields.\n\n    **Guarantees:**\n\n        - No route can exist without an OpenAPI declaration.\n        - No OpenAPI operation can exist without a handler.\n        - Swagger UI and ``/openapi.json`` always reflect the provided spec.\n        - Handler functions remain framework-agnostic and testable.\n        - Auth enforcement is driven entirely by the spec — no manual\n          middleware or decorators required.\n\nExample:\n    ```python\n    from openapi_first import OpenAPIFirstApp\n    import app.routes as routes\n\n    app = OpenAPIFirstApp(\n        openapi_path=\"app/openapi.json\",\n        routes_module=routes,\n        title=\"Example Service\",\n    )\n    ```",
         "members": {
           "openapi": {
             "name": "openapi",

docs/mcp/modules/openapi_first.templates.health_app.json

@@ -16,7 +16,7 @@
             "kind": "class",
             "path": "openapi_first.templates.health_app.main.OpenAPIFirstApp",
             "signature": "<bound method Alias.signature of Alias('OpenAPIFirstApp', 'openapi_first.app.OpenAPIFirstApp')>",
-            "docstring": "FastAPI application enforcing OpenAPI-first design.\n\nNotes:\n    **Responsibilities:**\n\n        - `OpenAPIFirstApp` subclasses `FastAPI` and replaces manual route\n          registration with OpenAPI-driven binding.\n        - All routes are derived from the provided OpenAPI specification,\n          and each `operationId` is mapped to a Python function in the\n          supplied routes module.\n\n    **Guarantees:**\n\n        - No route can exist without an OpenAPI declaration.\n        - No OpenAPI operation can exist without a handler.\n        - Swagger UI and `/openapi.json` always reflect the provided spec.\n        - Handler functions remain framework-agnostic and testable.\n\nExample:\n    ```python\n    from openapi_first import OpenAPIFirstApp\n    import app.routes as routes\n\n    app = OpenAPIFirstApp(\n        openapi_path=\"app/openapi.json\",\n        routes_module=routes,\n        title=\"Example Service\",\n    )\n    ```",
+            "docstring": "FastAPI application enforcing OpenAPI-first design.\n\nNotes:\n    **Responsibilities:**\n\n        - `OpenAPIFirstApp` subclasses `FastAPI` and replaces manual route\n          registration with OpenAPI-driven binding.\n        - All routes are derived from the provided OpenAPI specification,\n          and each ``operationId`` is mapped to a Python function in the\n          supplied routes module.\n        - Auth dependencies are auto-injected from the spec's\n          ``securitySchemes`` and per-operation ``security`` fields.\n\n    **Guarantees:**\n\n        - No route can exist without an OpenAPI declaration.\n        - No OpenAPI operation can exist without a handler.\n        - Swagger UI and ``/openapi.json`` always reflect the provided spec.\n        - Handler functions remain framework-agnostic and testable.\n        - Auth enforcement is driven entirely by the spec — no manual\n          middleware or decorators required.\n\nExample:\n    ```python\n    from openapi_first import OpenAPIFirstApp\n    import app.routes as routes\n\n    app = OpenAPIFirstApp(\n        openapi_path=\"app/openapi.json\",\n        routes_module=routes,\n        title=\"Example Service\",\n    )\n    ```",
             "members": {
               "openapi": {
                 "name": "openapi",

docs/mcp/modules/openapi_first.templates.health_app.main.json

@@ -9,7 +9,7 @@
         "kind": "class",
         "path": "openapi_first.templates.health_app.main.OpenAPIFirstApp",
         "signature": "<bound method Alias.signature of Alias('OpenAPIFirstApp', 'openapi_first.app.OpenAPIFirstApp')>",
-        "docstring": "FastAPI application enforcing OpenAPI-first design.\n\nNotes:\n    **Responsibilities:**\n\n        - `OpenAPIFirstApp` subclasses `FastAPI` and replaces manual route\n          registration with OpenAPI-driven binding.\n        - All routes are derived from the provided OpenAPI specification,\n          and each `operationId` is mapped to a Python function in the\n          supplied routes module.\n\n    **Guarantees:**\n\n        - No route can exist without an OpenAPI declaration.\n        - No OpenAPI operation can exist without a handler.\n        - Swagger UI and `/openapi.json` always reflect the provided spec.\n        - Handler functions remain framework-agnostic and testable.\n\nExample:\n    ```python\n    from openapi_first import OpenAPIFirstApp\n    import app.routes as routes\n\n    app = OpenAPIFirstApp(\n        openapi_path=\"app/openapi.json\",\n        routes_module=routes,\n        title=\"Example Service\",\n    )\n    ```",
+        "docstring": "FastAPI application enforcing OpenAPI-first design.\n\nNotes:\n    **Responsibilities:**\n\n        - `OpenAPIFirstApp` subclasses `FastAPI` and replaces manual route\n          registration with OpenAPI-driven binding.\n        - All routes are derived from the provided OpenAPI specification,\n          and each ``operationId`` is mapped to a Python function in the\n          supplied routes module.\n        - Auth dependencies are auto-injected from the spec's\n          ``securitySchemes`` and per-operation ``security`` fields.\n\n    **Guarantees:**\n\n        - No route can exist without an OpenAPI declaration.\n        - No OpenAPI operation can exist without a handler.\n        - Swagger UI and ``/openapi.json`` always reflect the provided spec.\n        - Handler functions remain framework-agnostic and testable.\n        - Auth enforcement is driven entirely by the spec — no manual\n          middleware or decorators required.\n\nExample:\n    ```python\n    from openapi_first import OpenAPIFirstApp\n    import app.routes as routes\n\n    app = OpenAPIFirstApp(\n        openapi_path=\"app/openapi.json\",\n        routes_module=routes,\n        title=\"Example Service\",\n    )\n    ```",
         "members": {
           "openapi": {
             "name": "openapi",

docs/mcp/modules/openapi_first.templates.model_app.json

@@ -81,7 +81,7 @@
             "kind": "class",
             "path": "openapi_first.templates.model_app.main.OpenAPIFirstApp",
             "signature": "<bound method Alias.signature of Alias('OpenAPIFirstApp', 'openapi_first.app.OpenAPIFirstApp')>",
-            "docstring": "FastAPI application enforcing OpenAPI-first design.\n\nNotes:\n    **Responsibilities:**\n\n        - `OpenAPIFirstApp` subclasses `FastAPI` and replaces manual route\n          registration with OpenAPI-driven binding.\n        - All routes are derived from the provided OpenAPI specification,\n          and each `operationId` is mapped to a Python function in the\n          supplied routes module.\n\n    **Guarantees:**\n\n        - No route can exist without an OpenAPI declaration.\n        - No OpenAPI operation can exist without a handler.\n        - Swagger UI and `/openapi.json` always reflect the provided spec.\n        - Handler functions remain framework-agnostic and testable.\n\nExample:\n    ```python\n    from openapi_first import OpenAPIFirstApp\n    import app.routes as routes\n\n    app = OpenAPIFirstApp(\n        openapi_path=\"app/openapi.json\",\n        routes_module=routes,\n        title=\"Example Service\",\n    )\n    ```",
+            "docstring": "FastAPI application enforcing OpenAPI-first design.\n\nNotes:\n    **Responsibilities:**\n\n        - `OpenAPIFirstApp` subclasses `FastAPI` and replaces manual route\n          registration with OpenAPI-driven binding.\n        - All routes are derived from the provided OpenAPI specification,\n          and each ``operationId`` is mapped to a Python function in the\n          supplied routes module.\n        - Auth dependencies are auto-injected from the spec's\n          ``securitySchemes`` and per-operation ``security`` fields.\n\n    **Guarantees:**\n\n        - No route can exist without an OpenAPI declaration.\n        - No OpenAPI operation can exist without a handler.\n        - Swagger UI and ``/openapi.json`` always reflect the provided spec.\n        - Handler functions remain framework-agnostic and testable.\n        - Auth enforcement is driven entirely by the spec — no manual\n          middleware or decorators required.\n\nExample:\n    ```python\n    from openapi_first import OpenAPIFirstApp\n    import app.routes as routes\n\n    app = OpenAPIFirstApp(\n        openapi_path=\"app/openapi.json\",\n        routes_module=routes,\n        title=\"Example Service\",\n    )\n    ```",
             "members": {
               "openapi": {
                 "name": "openapi",

docs/mcp/modules/openapi_first.templates.model_app.main.json

@@ -9,7 +9,7 @@
         "kind": "class",
         "path": "openapi_first.templates.model_app.main.OpenAPIFirstApp",
         "signature": "<bound method Alias.signature of Alias('OpenAPIFirstApp', 'openapi_first.app.OpenAPIFirstApp')>",
-        "docstring": "FastAPI application enforcing OpenAPI-first design.\n\nNotes:\n    **Responsibilities:**\n\n        - `OpenAPIFirstApp` subclasses `FastAPI` and replaces manual route\n          registration with OpenAPI-driven binding.\n        - All routes are derived from the provided OpenAPI specification,\n          and each `operationId` is mapped to a Python function in the\n          supplied routes module.\n\n    **Guarantees:**\n\n        - No route can exist without an OpenAPI declaration.\n        - No OpenAPI operation can exist without a handler.\n        - Swagger UI and `/openapi.json` always reflect the provided spec.\n        - Handler functions remain framework-agnostic and testable.\n\nExample:\n    ```python\n    from openapi_first import OpenAPIFirstApp\n    import app.routes as routes\n\n    app = OpenAPIFirstApp(\n        openapi_path=\"app/openapi.json\",\n        routes_module=routes,\n        title=\"Example Service\",\n    )\n    ```",
+        "docstring": "FastAPI application enforcing OpenAPI-first design.\n\nNotes:\n    **Responsibilities:**\n\n        - `OpenAPIFirstApp` subclasses `FastAPI` and replaces manual route\n          registration with OpenAPI-driven binding.\n        - All routes are derived from the provided OpenAPI specification,\n          and each ``operationId`` is mapped to a Python function in the\n          supplied routes module.\n        - Auth dependencies are auto-injected from the spec's\n          ``securitySchemes`` and per-operation ``security`` fields.\n\n    **Guarantees:**\n\n        - No route can exist without an OpenAPI declaration.\n        - No OpenAPI operation can exist without a handler.\n        - Swagger UI and ``/openapi.json`` always reflect the provided spec.\n        - Handler functions remain framework-agnostic and testable.\n        - Auth enforcement is driven entirely by the spec — no manual\n          middleware or decorators required.\n\nExample:\n    ```python\n    from openapi_first import OpenAPIFirstApp\n    import app.routes as routes\n\n    app = OpenAPIFirstApp(\n        openapi_path=\"app/openapi.json\",\n        routes_module=routes,\n        title=\"Example Service\",\n    )\n    ```",
         "members": {
           "openapi": {
             "name": "openapi",

docs/mcp/modules/openapi_first.templates.vet_app.data.json

@@ -0,0 +1,324 @@
+{
+  "module": "openapi_first.templates.vet_app.data",
+  "content": {
+    "path": "openapi_first.templates.vet_app.data",
+    "docstring": "In-memory data store for the Veterinary Clinic example.\n\nThis module is NOT thread-safe and is intended for demos and scaffolds only.\n\nIt provides minimal, process-local data stores for the five veterinary\nclinic entities. Each store exposes standard CRUD operations backed by\na simple dictionary.\n\nThis module intentionally avoids:\n- persistence\n- concurrency guarantees\n- transactional semantics\n- validation beyond what Pydantic provides\n\nThis module is not part of the ``openapi_first`` library API surface.",
+    "objects": {
+      "date": {
+        "name": "date",
+        "kind": "alias",
+        "path": "openapi_first.templates.vet_app.data.date",
+        "signature": "<bound method Alias.signature of Alias('date', 'datetime.date')>",
+        "docstring": null
+      },
+      "datetime": {
+        "name": "datetime",
+        "kind": "alias",
+        "path": "openapi_first.templates.vet_app.data.datetime",
+        "signature": "<bound method Alias.signature of Alias('datetime', 'datetime.datetime')>",
+        "docstring": null
+      },
+      "timezone": {
+        "name": "timezone",
+        "kind": "alias",
+        "path": "openapi_first.templates.vet_app.data.timezone",
+        "signature": "<bound method Alias.signature of Alias('timezone', 'datetime.timezone')>",
+        "docstring": null
+      },
+      "Parent": {
+        "name": "Parent",
+        "kind": "alias",
+        "path": "openapi_first.templates.vet_app.data.Parent",
+        "signature": "<bound method Alias.signature of Alias('Parent', 'models.Parent')>",
+        "docstring": null
+      },
+      "ParentCreate": {
+        "name": "ParentCreate",
+        "kind": "alias",
+        "path": "openapi_first.templates.vet_app.data.ParentCreate",
+        "signature": "<bound method Alias.signature of Alias('ParentCreate', 'models.ParentCreate')>",
+        "docstring": null
+      },
+      "Vet": {
+        "name": "Vet",
+        "kind": "alias",
+        "path": "openapi_first.templates.vet_app.data.Vet",
+        "signature": "<bound method Alias.signature of Alias('Vet', 'models.Vet')>",
+        "docstring": null
+      },
+      "VetCreate": {
+        "name": "VetCreate",
+        "kind": "alias",
+        "path": "openapi_first.templates.vet_app.data.VetCreate",
+        "signature": "<bound method Alias.signature of Alias('VetCreate', 'models.VetCreate')>",
+        "docstring": null
+      },
+      "Treatment": {
+        "name": "Treatment",
+        "kind": "alias",
+        "path": "openapi_first.templates.vet_app.data.Treatment",
+        "signature": "<bound method Alias.signature of Alias('Treatment', 'models.Treatment')>",
+        "docstring": null
+      },
+      "TreatmentCreate": {
+        "name": "TreatmentCreate",
+        "kind": "alias",
+        "path": "openapi_first.templates.vet_app.data.TreatmentCreate",
+        "signature": "<bound method Alias.signature of Alias('TreatmentCreate', 'models.TreatmentCreate')>",
+        "docstring": null
+      },
+      "Procedure": {
+        "name": "Procedure",
+        "kind": "alias",
+        "path": "openapi_first.templates.vet_app.data.Procedure",
+        "signature": "<bound method Alias.signature of Alias('Procedure', 'models.Procedure')>",
+        "docstring": null
+      },
+      "BasicNote": {
+        "name": "BasicNote",
+        "kind": "alias",
+        "path": "openapi_first.templates.vet_app.data.BasicNote",
+        "signature": "<bound method Alias.signature of Alias('BasicNote', 'models.BasicNote')>",
+        "docstring": null
+      },
+      "HeartRateNote": {
+        "name": "HeartRateNote",
+        "kind": "alias",
+        "path": "openapi_first.templates.vet_app.data.HeartRateNote",
+        "signature": "<bound method Alias.signature of Alias('HeartRateNote', 'models.HeartRateNote')>",
+        "docstring": null
+      },
+      "DentalNote": {
+        "name": "DentalNote",
+        "kind": "alias",
+        "path": "openapi_first.templates.vet_app.data.DentalNote",
+        "signature": "<bound method Alias.signature of Alias('DentalNote', 'models.DentalNote')>",
+        "docstring": null
+      },
+      "VaccineNote": {
+        "name": "VaccineNote",
+        "kind": "alias",
+        "path": "openapi_first.templates.vet_app.data.VaccineNote",
+        "signature": "<bound method Alias.signature of Alias('VaccineNote', 'models.VaccineNote')>",
+        "docstring": null
+      },
+      "PreOpNote": {
+        "name": "PreOpNote",
+        "kind": "alias",
+        "path": "openapi_first.templates.vet_app.data.PreOpNote",
+        "signature": "<bound method Alias.signature of Alias('PreOpNote', 'models.PreOpNote')>",
+        "docstring": null
+      },
+      "SurgeryNote": {
+        "name": "SurgeryNote",
+        "kind": "alias",
+        "path": "openapi_first.templates.vet_app.data.SurgeryNote",
+        "signature": "<bound method Alias.signature of Alias('SurgeryNote', 'models.SurgeryNote')>",
+        "docstring": null
+      },
+      "Pet": {
+        "name": "Pet",
+        "kind": "alias",
+        "path": "openapi_first.templates.vet_app.data.Pet",
+        "signature": "<bound method Alias.signature of Alias('Pet', 'models.Pet')>",
+        "docstring": null
+      },
+      "PetCreate": {
+        "name": "PetCreate",
+        "kind": "alias",
+        "path": "openapi_first.templates.vet_app.data.PetCreate",
+        "signature": "<bound method Alias.signature of Alias('PetCreate', 'models.PetCreate')>",
+        "docstring": null
+      },
+      "Appointment": {
+        "name": "Appointment",
+        "kind": "alias",
+        "path": "openapi_first.templates.vet_app.data.Appointment",
+        "signature": "<bound method Alias.signature of Alias('Appointment', 'models.Appointment')>",
+        "docstring": null
+      },
+      "AppointmentCreate": {
+        "name": "AppointmentCreate",
+        "kind": "alias",
+        "path": "openapi_first.templates.vet_app.data.AppointmentCreate",
+        "signature": "<bound method Alias.signature of Alias('AppointmentCreate', 'models.AppointmentCreate')>",
+        "docstring": null
+      },
+      "list_parents": {
+        "name": "list_parents",
+        "kind": "function",
+        "path": "openapi_first.templates.vet_app.data.list_parents",
+        "signature": "<bound method Function.signature of Function('list_parents', 45, 46)>",
+        "docstring": null
+      },
+      "get_parent": {
+        "name": "get_parent",
+        "kind": "function",
+        "path": "openapi_first.templates.vet_app.data.get_parent",
+        "signature": "<bound method Function.signature of Function('get_parent', 49, 50)>",
+        "docstring": null
+      },
+      "create_parent": {
+        "name": "create_parent",
+        "kind": "function",
+        "path": "openapi_first.templates.vet_app.data.create_parent",
+        "signature": "<bound method Function.signature of Function('create_parent', 53, 65)>",
+        "docstring": null
+      },
+      "update_parent": {
+        "name": "update_parent",
+        "kind": "function",
+        "path": "openapi_first.templates.vet_app.data.update_parent",
+        "signature": "<bound method Function.signature of Function('update_parent', 68, 81)>",
+        "docstring": null
+      },
+      "delete_parent": {
+        "name": "delete_parent",
+        "kind": "function",
+        "path": "openapi_first.templates.vet_app.data.delete_parent",
+        "signature": "<bound method Function.signature of Function('delete_parent', 84, 85)>",
+        "docstring": null
+      },
+      "list_vets": {
+        "name": "list_vets",
+        "kind": "function",
+        "path": "openapi_first.templates.vet_app.data.list_vets",
+        "signature": "<bound method Function.signature of Function('list_vets', 96, 97)>",
+        "docstring": null
+      },
+      "get_vet": {
+        "name": "get_vet",
+        "kind": "function",
+        "path": "openapi_first.templates.vet_app.data.get_vet",
+        "signature": "<bound method Function.signature of Function('get_vet', 100, 101)>",
+        "docstring": null
+      },
+      "create_vet": {
+        "name": "create_vet",
+        "kind": "function",
+        "path": "openapi_first.templates.vet_app.data.create_vet",
+        "signature": "<bound method Function.signature of Function('create_vet', 104, 117)>",
+        "docstring": null
+      },
+      "update_vet": {
+        "name": "update_vet",
+        "kind": "function",
+        "path": "openapi_first.templates.vet_app.data.update_vet",
+        "signature": "<bound method Function.signature of Function('update_vet', 120, 134)>",
+        "docstring": null
+      },
+      "delete_vet": {
+        "name": "delete_vet",
+        "kind": "function",
+        "path": "openapi_first.templates.vet_app.data.delete_vet",
+        "signature": "<bound method Function.signature of Function('delete_vet', 137, 138)>",
+        "docstring": null
+      },
+      "list_treatments": {
+        "name": "list_treatments",
+        "kind": "function",
+        "path": "openapi_first.templates.vet_app.data.list_treatments",
+        "signature": "<bound method Function.signature of Function('list_treatments', 149, 150)>",
+        "docstring": null
+      },
+      "get_treatment": {
+        "name": "get_treatment",
+        "kind": "function",
+        "path": "openapi_first.templates.vet_app.data.get_treatment",
+        "signature": "<bound method Function.signature of Function('get_treatment', 153, 154)>",
+        "docstring": null
+      },
+      "create_treatment": {
+        "name": "create_treatment",
+        "kind": "function",
+        "path": "openapi_first.templates.vet_app.data.create_treatment",
+        "signature": "<bound method Function.signature of Function('create_treatment', 157, 168)>",
+        "docstring": null
+      },
+      "update_treatment": {
+        "name": "update_treatment",
+        "kind": "function",
+        "path": "openapi_first.templates.vet_app.data.update_treatment",
+        "signature": "<bound method Function.signature of Function('update_treatment', 171, 183)>",
+        "docstring": null
+      },
+      "delete_treatment": {
+        "name": "delete_treatment",
+        "kind": "function",
+        "path": "openapi_first.templates.vet_app.data.delete_treatment",
+        "signature": "<bound method Function.signature of Function('delete_treatment', 186, 187)>",
+        "docstring": null
+      },
+      "list_pets": {
+        "name": "list_pets",
+        "kind": "function",
+        "path": "openapi_first.templates.vet_app.data.list_pets",
+        "signature": "<bound method Function.signature of Function('list_pets', 198, 199)>",
+        "docstring": null
+      },
+      "get_pet": {
+        "name": "get_pet",
+        "kind": "function",
+        "path": "openapi_first.templates.vet_app.data.get_pet",
+        "signature": "<bound method Function.signature of Function('get_pet', 202, 203)>",
+        "docstring": null
+      },
+      "create_pet": {
+        "name": "create_pet",
+        "kind": "function",
+        "path": "openapi_first.templates.vet_app.data.create_pet",
+        "signature": "<bound method Function.signature of Function('create_pet', 206, 223)>",
+        "docstring": null
+      },
+      "update_pet": {
+        "name": "update_pet",
+        "kind": "function",
+        "path": "openapi_first.templates.vet_app.data.update_pet",
+        "signature": "<bound method Function.signature of Function('update_pet', 226, 244)>",
+        "docstring": null
+      },
+      "delete_pet": {
+        "name": "delete_pet",
+        "kind": "function",
+        "path": "openapi_first.templates.vet_app.data.delete_pet",
+        "signature": "<bound method Function.signature of Function('delete_pet', 247, 248)>",
+        "docstring": null
+      },
+      "list_appointments": {
+        "name": "list_appointments",
+        "kind": "function",
+        "path": "openapi_first.templates.vet_app.data.list_appointments",
+        "signature": "<bound method Function.signature of Function('list_appointments', 259, 260)>",
+        "docstring": null
+      },
+      "get_appointment": {
+        "name": "get_appointment",
+        "kind": "function",
+        "path": "openapi_first.templates.vet_app.data.get_appointment",
+        "signature": "<bound method Function.signature of Function('get_appointment', 263, 264)>",
+        "docstring": null
+      },
+      "create_appointment": {
+        "name": "create_appointment",
+        "kind": "function",
+        "path": "openapi_first.templates.vet_app.data.create_appointment",
+        "signature": "<bound method Function.signature of Function('create_appointment', 267, 282)>",
+        "docstring": null
+      },
+      "update_appointment": {
+        "name": "update_appointment",
+        "kind": "function",
+        "path": "openapi_first.templates.vet_app.data.update_appointment",
+        "signature": "<bound method Function.signature of Function('update_appointment', 285, 301)>",
+        "docstring": null
+      },
+      "delete_appointment": {
+        "name": "delete_appointment",
+        "kind": "function",
+        "path": "openapi_first.templates.vet_app.data.delete_appointment",
+        "signature": "<bound method Function.signature of Function('delete_appointment', 304, 305)>",
+        "docstring": null
+      }
+    }
+  }
+}

docs/mcp/modules/openapi_first.templates.vet_app.main.json

@@ -0,0 +1,60 @@
+{
+  "module": "openapi_first.templates.vet_app.main",
+  "content": {
+    "path": "openapi_first.templates.vet_app.main",
+    "docstring": "Application entry point for an OpenAPI-first Veterinary Clinic service.\n\nThis module constructs a FastAPI application exclusively from an\nOpenAPI specification and a handler namespace, without using\ndecorator-driven routing.\n\nAll HTTP routes, methods, request/response schemas, and operation\nbindings are defined in the OpenAPI document referenced by\n``openapi_path``. Python callables defined in the ``routes`` module are\nbound to OpenAPI operations strictly via ``operationId``.\n\nThis module contains no routing logic, persistence concerns, or\nframework configuration beyond application assembly.\n\nDesign guarantees:\n- OpenAPI is the single source of truth\n- No undocumented routes can exist\n- Every OpenAPI operationId must resolve to exactly one handler\n- All contract violations fail at application startup\n\nThis file is intended to be used as the ASGI entry point.\n\nExample:\n    uvicorn main:app",
+    "objects": {
+      "asynccontextmanager": {
+        "name": "asynccontextmanager",
+        "kind": "alias",
+        "path": "openapi_first.templates.vet_app.main.asynccontextmanager",
+        "signature": "<bound method Alias.signature of Alias('asynccontextmanager', 'contextlib.asynccontextmanager')>",
+        "docstring": null
+      },
+      "CORSMiddleware": {
+        "name": "CORSMiddleware",
+        "kind": "alias",
+        "path": "openapi_first.templates.vet_app.main.CORSMiddleware",
+        "signature": "<bound method Alias.signature of Alias('CORSMiddleware', 'starlette.middleware.cors.CORSMiddleware')>",
+        "docstring": null
+      },
+      "OpenAPIFirstApp": {
+        "name": "OpenAPIFirstApp",
+        "kind": "class",
+        "path": "openapi_first.templates.vet_app.main.OpenAPIFirstApp",
+        "signature": "<bound method Alias.signature of Alias('OpenAPIFirstApp', 'openapi_first.app.OpenAPIFirstApp')>",
+        "docstring": "FastAPI application enforcing OpenAPI-first design.\n\nNotes:\n    **Responsibilities:**\n\n        - `OpenAPIFirstApp` subclasses `FastAPI` and replaces manual route\n          registration with OpenAPI-driven binding.\n        - All routes are derived from the provided OpenAPI specification,\n          and each ``operationId`` is mapped to a Python function in the\n          supplied routes module.\n        - Auth dependencies are auto-injected from the spec's\n          ``securitySchemes`` and per-operation ``security`` fields.\n\n    **Guarantees:**\n\n        - No route can exist without an OpenAPI declaration.\n        - No OpenAPI operation can exist without a handler.\n        - Swagger UI and ``/openapi.json`` always reflect the provided spec.\n        - Handler functions remain framework-agnostic and testable.\n        - Auth enforcement is driven entirely by the spec — no manual\n          middleware or decorators required.\n\nExample:\n    ```python\n    from openapi_first import OpenAPIFirstApp\n    import app.routes as routes\n\n    app = OpenAPIFirstApp(\n        openapi_path=\"app/openapi.json\",\n        routes_module=routes,\n        title=\"Example Service\",\n    )\n    ```",
+        "members": {
+          "openapi": {
+            "name": "openapi",
+            "kind": "attribute",
+            "path": "openapi_first.templates.vet_app.main.OpenAPIFirstApp.openapi",
+            "signature": "<bound method Alias.signature of Alias('openapi', 'openapi_first.app.OpenAPIFirstApp.openapi')>",
+            "docstring": null
+          }
+        }
+      },
+      "routes": {
+        "name": "routes",
+        "kind": "alias",
+        "path": "openapi_first.templates.vet_app.main.routes",
+        "signature": "<bound method Alias.signature of Alias('routes', 'routes')>",
+        "docstring": null
+      },
+      "lifespan": {
+        "name": "lifespan",
+        "kind": "function",
+        "path": "openapi_first.templates.vet_app.main.lifespan",
+        "signature": "<bound method Function.signature of Function('lifespan', 34, 39)>",
+        "docstring": null
+      },
+      "app": {
+        "name": "app",
+        "kind": "attribute",
+        "path": "openapi_first.templates.vet_app.main.app",
+        "signature": null,
+        "docstring": null
+      }
+    }
+  }
+}

docs/mcp/modules/openapi_first.templates.vet_app.models.json

@@ -0,0 +1,681 @@
+{
+  "module": "openapi_first.templates.vet_app.models",
+  "content": {
+    "path": "openapi_first.templates.vet_app.models",
+    "docstring": null,
+    "objects": {
+      "date": {
+        "name": "date",
+        "kind": "alias",
+        "path": "openapi_first.templates.vet_app.models.date",
+        "signature": "<bound method Alias.signature of Alias('date', 'datetime.date')>",
+        "docstring": null
+      },
+      "datetime": {
+        "name": "datetime",
+        "kind": "alias",
+        "path": "openapi_first.templates.vet_app.models.datetime",
+        "signature": "<bound method Alias.signature of Alias('datetime', 'datetime.datetime')>",
+        "docstring": null
+      },
+      "Annotated": {
+        "name": "Annotated",
+        "kind": "alias",
+        "path": "openapi_first.templates.vet_app.models.Annotated",
+        "signature": "<bound method Alias.signature of Alias('Annotated', 'typing.Annotated')>",
+        "docstring": null
+      },
+      "Literal": {
+        "name": "Literal",
+        "kind": "alias",
+        "path": "openapi_first.templates.vet_app.models.Literal",
+        "signature": "<bound method Alias.signature of Alias('Literal', 'typing.Literal')>",
+        "docstring": null
+      },
+      "BaseModel": {
+        "name": "BaseModel",
+        "kind": "alias",
+        "path": "openapi_first.templates.vet_app.models.BaseModel",
+        "signature": "<bound method Alias.signature of Alias('BaseModel', 'pydantic.BaseModel')>",
+        "docstring": null
+      },
+      "Field": {
+        "name": "Field",
+        "kind": "alias",
+        "path": "openapi_first.templates.vet_app.models.Field",
+        "signature": "<bound method Alias.signature of Alias('Field', 'pydantic.Field')>",
+        "docstring": null
+      },
+      "Metadata": {
+        "name": "Metadata",
+        "kind": "class",
+        "path": "openapi_first.templates.vet_app.models.Metadata",
+        "signature": "<bound method Class.signature of Class('Metadata', 6, 8)>",
+        "docstring": null,
+        "members": {
+          "createdOn": {
+            "name": "createdOn",
+            "kind": "attribute",
+            "path": "openapi_first.templates.vet_app.models.Metadata.createdOn",
+            "signature": null,
+            "docstring": null
+          },
+          "updatedOn": {
+            "name": "updatedOn",
+            "kind": "attribute",
+            "path": "openapi_first.templates.vet_app.models.Metadata.updatedOn",
+            "signature": null,
+            "docstring": null
+          }
+        }
+      },
+      "ParentBase": {
+        "name": "ParentBase",
+        "kind": "class",
+        "path": "openapi_first.templates.vet_app.models.ParentBase",
+        "signature": "<bound method Class.signature of Class('ParentBase', 11, 15)>",
+        "docstring": null,
+        "members": {
+          "name": {
+            "name": "name",
+            "kind": "attribute",
+            "path": "openapi_first.templates.vet_app.models.ParentBase.name",
+            "signature": null,
+            "docstring": null
+          },
+          "email": {
+            "name": "email",
+            "kind": "attribute",
+            "path": "openapi_first.templates.vet_app.models.ParentBase.email",
+            "signature": null,
+            "docstring": null
+          },
+          "phone": {
+            "name": "phone",
+            "kind": "attribute",
+            "path": "openapi_first.templates.vet_app.models.ParentBase.phone",
+            "signature": null,
+            "docstring": null
+          },
+          "metadata": {
+            "name": "metadata",
+            "kind": "attribute",
+            "path": "openapi_first.templates.vet_app.models.ParentBase.metadata",
+            "signature": null,
+            "docstring": null
+          }
+        }
+      },
+      "ParentCreate": {
+        "name": "ParentCreate",
+        "kind": "class",
+        "path": "openapi_first.templates.vet_app.models.ParentCreate",
+        "signature": "<bound method Class.signature of Class('ParentCreate', 18, 19)>",
+        "docstring": null
+      },
+      "Parent": {
+        "name": "Parent",
+        "kind": "class",
+        "path": "openapi_first.templates.vet_app.models.Parent",
+        "signature": "<bound method Class.signature of Class('Parent', 22, 23)>",
+        "docstring": null,
+        "members": {
+          "id": {
+            "name": "id",
+            "kind": "attribute",
+            "path": "openapi_first.templates.vet_app.models.Parent.id",
+            "signature": null,
+            "docstring": null
+          }
+        }
+      },
+      "VetBase": {
+        "name": "VetBase",
+        "kind": "class",
+        "path": "openapi_first.templates.vet_app.models.VetBase",
+        "signature": "<bound method Class.signature of Class('VetBase', 26, 31)>",
+        "docstring": null,
+        "members": {
+          "name": {
+            "name": "name",
+            "kind": "attribute",
+            "path": "openapi_first.templates.vet_app.models.VetBase.name",
+            "signature": null,
+            "docstring": null
+          },
+          "specialty": {
+            "name": "specialty",
+            "kind": "attribute",
+            "path": "openapi_first.templates.vet_app.models.VetBase.specialty",
+            "signature": null,
+            "docstring": null
+          },
+          "email": {
+            "name": "email",
+            "kind": "attribute",
+            "path": "openapi_first.templates.vet_app.models.VetBase.email",
+            "signature": null,
+            "docstring": null
+          },
+          "phone": {
+            "name": "phone",
+            "kind": "attribute",
+            "path": "openapi_first.templates.vet_app.models.VetBase.phone",
+            "signature": null,
+            "docstring": null
+          },
+          "metadata": {
+            "name": "metadata",
+            "kind": "attribute",
+            "path": "openapi_first.templates.vet_app.models.VetBase.metadata",
+            "signature": null,
+            "docstring": null
+          }
+        }
+      },
+      "VetCreate": {
+        "name": "VetCreate",
+        "kind": "class",
+        "path": "openapi_first.templates.vet_app.models.VetCreate",
+        "signature": "<bound method Class.signature of Class('VetCreate', 34, 35)>",
+        "docstring": null
+      },
+      "Vet": {
+        "name": "Vet",
+        "kind": "class",
+        "path": "openapi_first.templates.vet_app.models.Vet",
+        "signature": "<bound method Class.signature of Class('Vet', 38, 39)>",
+        "docstring": null,
+        "members": {
+          "id": {
+            "name": "id",
+            "kind": "attribute",
+            "path": "openapi_first.templates.vet_app.models.Vet.id",
+            "signature": null,
+            "docstring": null
+          }
+        }
+      },
+      "ProcedureNoteBase": {
+        "name": "ProcedureNoteBase",
+        "kind": "class",
+        "path": "openapi_first.templates.vet_app.models.ProcedureNoteBase",
+        "signature": "<bound method Class.signature of Class('ProcedureNoteBase', 42, 44)>",
+        "docstring": null,
+        "members": {
+          "summary": {
+            "name": "summary",
+            "kind": "attribute",
+            "path": "openapi_first.templates.vet_app.models.ProcedureNoteBase.summary",
+            "signature": null,
+            "docstring": null
+          },
+          "details": {
+            "name": "details",
+            "kind": "attribute",
+            "path": "openapi_first.templates.vet_app.models.ProcedureNoteBase.details",
+            "signature": null,
+            "docstring": null
+          }
+        }
+      },
+      "BasicNote": {
+        "name": "BasicNote",
+        "kind": "class",
+        "path": "openapi_first.templates.vet_app.models.BasicNote",
+        "signature": "<bound method Class.signature of Class('BasicNote', 47, 48)>",
+        "docstring": null,
+        "members": {
+          "noteType": {
+            "name": "noteType",
+            "kind": "attribute",
+            "path": "openapi_first.templates.vet_app.models.BasicNote.noteType",
+            "signature": null,
+            "docstring": null
+          }
+        }
+      },
+      "HeartRateNote": {
+        "name": "HeartRateNote",
+        "kind": "class",
+        "path": "openapi_first.templates.vet_app.models.HeartRateNote",
+        "signature": "<bound method Class.signature of Class('HeartRateNote', 51, 53)>",
+        "docstring": null,
+        "members": {
+          "noteType": {
+            "name": "noteType",
+            "kind": "attribute",
+            "path": "openapi_first.templates.vet_app.models.HeartRateNote.noteType",
+            "signature": null,
+            "docstring": null
+          },
+          "bpm": {
+            "name": "bpm",
+            "kind": "attribute",
+            "path": "openapi_first.templates.vet_app.models.HeartRateNote.bpm",
+            "signature": null,
+            "docstring": null
+          }
+        }
+      },
+      "DentalNote": {
+        "name": "DentalNote",
+        "kind": "class",
+        "path": "openapi_first.templates.vet_app.models.DentalNote",
+        "signature": "<bound method Class.signature of Class('DentalNote', 56, 59)>",
+        "docstring": null,
+        "members": {
+          "noteType": {
+            "name": "noteType",
+            "kind": "attribute",
+            "path": "openapi_first.templates.vet_app.models.DentalNote.noteType",
+            "signature": null,
+            "docstring": null
+          },
+          "procedureType": {
+            "name": "procedureType",
+            "kind": "attribute",
+            "path": "openapi_first.templates.vet_app.models.DentalNote.procedureType",
+            "signature": null,
+            "docstring": null
+          },
+          "teeth": {
+            "name": "teeth",
+            "kind": "attribute",
+            "path": "openapi_first.templates.vet_app.models.DentalNote.teeth",
+            "signature": null,
+            "docstring": null
+          }
+        }
+      },
+      "VaccineNote": {
+        "name": "VaccineNote",
+        "kind": "class",
+        "path": "openapi_first.templates.vet_app.models.VaccineNote",
+        "signature": "<bound method Class.signature of Class('VaccineNote', 62, 65)>",
+        "docstring": null,
+        "members": {
+          "noteType": {
+            "name": "noteType",
+            "kind": "attribute",
+            "path": "openapi_first.templates.vet_app.models.VaccineNote.noteType",
+            "signature": null,
+            "docstring": null
+          },
+          "medicine": {
+            "name": "medicine",
+            "kind": "attribute",
+            "path": "openapi_first.templates.vet_app.models.VaccineNote.medicine",
+            "signature": null,
+            "docstring": null
+          },
+          "leg": {
+            "name": "leg",
+            "kind": "attribute",
+            "path": "openapi_first.templates.vet_app.models.VaccineNote.leg",
+            "signature": null,
+            "docstring": null
+          }
+        }
+      },
+      "PreOpNote": {
+        "name": "PreOpNote",
+        "kind": "class",
+        "path": "openapi_first.templates.vet_app.models.PreOpNote",
+        "signature": "<bound method Class.signature of Class('PreOpNote', 68, 71)>",
+        "docstring": null,
+        "members": {
+          "noteType": {
+            "name": "noteType",
+            "kind": "attribute",
+            "path": "openapi_first.templates.vet_app.models.PreOpNote.noteType",
+            "signature": null,
+            "docstring": null
+          },
+          "heartRate": {
+            "name": "heartRate",
+            "kind": "attribute",
+            "path": "openapi_first.templates.vet_app.models.PreOpNote.heartRate",
+            "signature": null,
+            "docstring": null
+          },
+          "temperature": {
+            "name": "temperature",
+            "kind": "attribute",
+            "path": "openapi_first.templates.vet_app.models.PreOpNote.temperature",
+            "signature": null,
+            "docstring": null
+          }
+        }
+      },
+      "SurgeryNote": {
+        "name": "SurgeryNote",
+        "kind": "class",
+        "path": "openapi_first.templates.vet_app.models.SurgeryNote",
+        "signature": "<bound method Class.signature of Class('SurgeryNote', 74, 77)>",
+        "docstring": null,
+        "members": {
+          "noteType": {
+            "name": "noteType",
+            "kind": "attribute",
+            "path": "openapi_first.templates.vet_app.models.SurgeryNote.noteType",
+            "signature": null,
+            "docstring": null
+          },
+          "surgeryType": {
+            "name": "surgeryType",
+            "kind": "attribute",
+            "path": "openapi_first.templates.vet_app.models.SurgeryNote.surgeryType",
+            "signature": null,
+            "docstring": null
+          },
+          "complications": {
+            "name": "complications",
+            "kind": "attribute",
+            "path": "openapi_first.templates.vet_app.models.SurgeryNote.complications",
+            "signature": null,
+            "docstring": null
+          }
+        }
+      },
+      "ProcedureNotes": {
+        "name": "ProcedureNotes",
+        "kind": "attribute",
+        "path": "openapi_first.templates.vet_app.models.ProcedureNotes",
+        "signature": null,
+        "docstring": null
+      },
+      "Procedure": {
+        "name": "Procedure",
+        "kind": "class",
+        "path": "openapi_first.templates.vet_app.models.Procedure",
+        "signature": "<bound method Class.signature of Class('Procedure', 86, 90)>",
+        "docstring": null,
+        "members": {
+          "name": {
+            "name": "name",
+            "kind": "attribute",
+            "path": "openapi_first.templates.vet_app.models.Procedure.name",
+            "signature": null,
+            "docstring": null
+          },
+          "description": {
+            "name": "description",
+            "kind": "attribute",
+            "path": "openapi_first.templates.vet_app.models.Procedure.description",
+            "signature": null,
+            "docstring": null
+          },
+          "cost": {
+            "name": "cost",
+            "kind": "attribute",
+            "path": "openapi_first.templates.vet_app.models.Procedure.cost",
+            "signature": null,
+            "docstring": null
+          },
+          "notes": {
+            "name": "notes",
+            "kind": "attribute",
+            "path": "openapi_first.templates.vet_app.models.Procedure.notes",
+            "signature": null,
+            "docstring": null
+          }
+        }
+      },
+      "TreatmentBase": {
+        "name": "TreatmentBase",
+        "kind": "class",
+        "path": "openapi_first.templates.vet_app.models.TreatmentBase",
+        "signature": "<bound method Class.signature of Class('TreatmentBase', 93, 96)>",
+        "docstring": null,
+        "members": {
+          "label": {
+            "name": "label",
+            "kind": "attribute",
+            "path": "openapi_first.templates.vet_app.models.TreatmentBase.label",
+            "signature": null,
+            "docstring": null
+          },
+          "description": {
+            "name": "description",
+            "kind": "attribute",
+            "path": "openapi_first.templates.vet_app.models.TreatmentBase.description",
+            "signature": null,
+            "docstring": null
+          },
+          "metadata": {
+            "name": "metadata",
+            "kind": "attribute",
+            "path": "openapi_first.templates.vet_app.models.TreatmentBase.metadata",
+            "signature": null,
+            "docstring": null
+          }
+        }
+      },
+      "TreatmentCreate": {
+        "name": "TreatmentCreate",
+        "kind": "class",
+        "path": "openapi_first.templates.vet_app.models.TreatmentCreate",
+        "signature": "<bound method Class.signature of Class('TreatmentCreate', 99, 100)>",
+        "docstring": null
+      },
+      "Treatment": {
+        "name": "Treatment",
+        "kind": "class",
+        "path": "openapi_first.templates.vet_app.models.Treatment",
+        "signature": "<bound method Class.signature of Class('Treatment', 103, 104)>",
+        "docstring": null,
+        "members": {
+          "id": {
+            "name": "id",
+            "kind": "attribute",
+            "path": "openapi_first.templates.vet_app.models.Treatment.id",
+            "signature": null,
+            "docstring": null
+          }
+        }
+      },
+      "PetBase": {
+        "name": "PetBase",
+        "kind": "class",
+        "path": "openapi_first.templates.vet_app.models.PetBase",
+        "signature": "<bound method Class.signature of Class('PetBase', 107, 114)>",
+        "docstring": null,
+        "members": {
+          "name": {
+            "name": "name",
+            "kind": "attribute",
+            "path": "openapi_first.templates.vet_app.models.PetBase.name",
+            "signature": null,
+            "docstring": null
+          },
+          "species": {
+            "name": "species",
+            "kind": "attribute",
+            "path": "openapi_first.templates.vet_app.models.PetBase.species",
+            "signature": null,
+            "docstring": null
+          },
+          "age": {
+            "name": "age",
+            "kind": "attribute",
+            "path": "openapi_first.templates.vet_app.models.PetBase.age",
+            "signature": null,
+            "docstring": null
+          },
+          "weight": {
+            "name": "weight",
+            "kind": "attribute",
+            "path": "openapi_first.templates.vet_app.models.PetBase.weight",
+            "signature": null,
+            "docstring": null
+          },
+          "birthDate": {
+            "name": "birthDate",
+            "kind": "attribute",
+            "path": "openapi_first.templates.vet_app.models.PetBase.birthDate",
+            "signature": null,
+            "docstring": null
+          },
+          "photo": {
+            "name": "photo",
+            "kind": "attribute",
+            "path": "openapi_first.templates.vet_app.models.PetBase.photo",
+            "signature": null,
+            "docstring": null
+          },
+          "metadata": {
+            "name": "metadata",
+            "kind": "attribute",
+            "path": "openapi_first.templates.vet_app.models.PetBase.metadata",
+            "signature": null,
+            "docstring": null
+          }
+        }
+      },
+      "PetCreate": {
+        "name": "PetCreate",
+        "kind": "class",
+        "path": "openapi_first.templates.vet_app.models.PetCreate",
+        "signature": "<bound method Class.signature of Class('PetCreate', 117, 118)>",
+        "docstring": null,
+        "members": {
+          "parent_ids": {
+            "name": "parent_ids",
+            "kind": "attribute",
+            "path": "openapi_first.templates.vet_app.models.PetCreate.parent_ids",
+            "signature": null,
+            "docstring": null
+          }
+        }
+      },
+      "Pet": {
+        "name": "Pet",
+        "kind": "class",
+        "path": "openapi_first.templates.vet_app.models.Pet",
+        "signature": "<bound method Class.signature of Class('Pet', 121, 123)>",
+        "docstring": null,
+        "members": {
+          "id": {
+            "name": "id",
+            "kind": "attribute",
+            "path": "openapi_first.templates.vet_app.models.Pet.id",
+            "signature": null,
+            "docstring": null
+          },
+          "parents": {
+            "name": "parents",
+            "kind": "attribute",
+            "path": "openapi_first.templates.vet_app.models.Pet.parents",
+            "signature": null,
+            "docstring": null
+          }
+        }
+      },
+      "AppointmentBase": {
+        "name": "AppointmentBase",
+        "kind": "class",
+        "path": "openapi_first.templates.vet_app.models.AppointmentBase",
+        "signature": "<bound method Class.signature of Class('AppointmentBase', 126, 130)>",
+        "docstring": null,
+        "members": {
+          "date": {
+            "name": "date",
+            "kind": "attribute",
+            "path": "openapi_first.templates.vet_app.models.AppointmentBase.date",
+            "signature": null,
+            "docstring": null
+          },
+          "notes": {
+            "name": "notes",
+            "kind": "attribute",
+            "path": "openapi_first.templates.vet_app.models.AppointmentBase.notes",
+            "signature": null,
+            "docstring": null
+          },
+          "procedures": {
+            "name": "procedures",
+            "kind": "attribute",
+            "path": "openapi_first.templates.vet_app.models.AppointmentBase.procedures",
+            "signature": null,
+            "docstring": null
+          },
+          "metadata": {
+            "name": "metadata",
+            "kind": "attribute",
+            "path": "openapi_first.templates.vet_app.models.AppointmentBase.metadata",
+            "signature": null,
+            "docstring": null
+          }
+        }
+      },
+      "AppointmentCreate": {
+        "name": "AppointmentCreate",
+        "kind": "class",
+        "path": "openapi_first.templates.vet_app.models.AppointmentCreate",
+        "signature": "<bound method Class.signature of Class('AppointmentCreate', 133, 136)>",
+        "docstring": null,
+        "members": {
+          "pet_id": {
+            "name": "pet_id",
+            "kind": "attribute",
+            "path": "openapi_first.templates.vet_app.models.AppointmentCreate.pet_id",
+            "signature": null,
+            "docstring": null
+          },
+          "vet_id": {
+            "name": "vet_id",
+            "kind": "attribute",
+            "path": "openapi_first.templates.vet_app.models.AppointmentCreate.vet_id",
+            "signature": null,
+            "docstring": null
+          },
+          "treatment_id": {
+            "name": "treatment_id",
+            "kind": "attribute",
+            "path": "openapi_first.templates.vet_app.models.AppointmentCreate.treatment_id",
+            "signature": null,
+            "docstring": null
+          }
+        }
+      },
+      "Appointment": {
+        "name": "Appointment",
+        "kind": "class",
+        "path": "openapi_first.templates.vet_app.models.Appointment",
+        "signature": "<bound method Class.signature of Class('Appointment', 139, 143)>",
+        "docstring": null,
+        "members": {
+          "id": {
+            "name": "id",
+            "kind": "attribute",
+            "path": "openapi_first.templates.vet_app.models.Appointment.id",
+            "signature": null,
+            "docstring": null
+          },
+          "pet": {
+            "name": "pet",
+            "kind": "attribute",
+            "path": "openapi_first.templates.vet_app.models.Appointment.pet",
+            "signature": null,
+            "docstring": null
+          },
+          "vet": {
+            "name": "vet",
+            "kind": "attribute",
+            "path": "openapi_first.templates.vet_app.models.Appointment.vet",
+            "signature": null,
+            "docstring": null
+          },
+          "treatment": {
+            "name": "treatment",
+            "kind": "attribute",
+            "path": "openapi_first.templates.vet_app.models.Appointment.treatment",
+            "signature": null,
+            "docstring": null
+          }
+        }
+      }
+    }
+  }
+}

docs/mcp/modules/openapi_first.templates.vet_app.routes.json

@@ -0,0 +1,275 @@
+{
+  "module": "openapi_first.templates.vet_app.routes",
+  "content": {
+    "path": "openapi_first.templates.vet_app.routes",
+    "docstring": "Veterinary Clinic route handlers bound via OpenAPI operationId.\n\nHandlers explicitly control HTTP response status codes to ensure runtime\nbehavior matches the OpenAPI contract. Domain models defined using\nPydantic are used for request and response payloads.\n\nNo routing decorators, path definitions, or implicit framework behavior\nappear in this module. All routing, HTTP methods, and schemas are defined\nin the OpenAPI specification.",
+    "objects": {
+      "Response": {
+        "name": "Response",
+        "kind": "alias",
+        "path": "openapi_first.templates.vet_app.routes.Response",
+        "signature": "<bound method Alias.signature of Alias('Response', 'fastapi.Response')>",
+        "docstring": null
+      },
+      "HTTPException": {
+        "name": "HTTPException",
+        "kind": "alias",
+        "path": "openapi_first.templates.vet_app.routes.HTTPException",
+        "signature": "<bound method Alias.signature of Alias('HTTPException', 'fastapi.HTTPException')>",
+        "docstring": null
+      },
+      "UploadFile": {
+        "name": "UploadFile",
+        "kind": "alias",
+        "path": "openapi_first.templates.vet_app.routes.UploadFile",
+        "signature": "<bound method Alias.signature of Alias('UploadFile', 'fastapi.UploadFile')>",
+        "docstring": null
+      },
+      "StreamingResponse": {
+        "name": "StreamingResponse",
+        "kind": "alias",
+        "path": "openapi_first.templates.vet_app.routes.StreamingResponse",
+        "signature": "<bound method Alias.signature of Alias('StreamingResponse', 'fastapi.responses.StreamingResponse')>",
+        "docstring": null
+      },
+      "subscribe": {
+        "name": "subscribe",
+        "kind": "alias",
+        "path": "openapi_first.templates.vet_app.routes.subscribe",
+        "signature": "<bound method Alias.signature of Alias('subscribe', 'sse.subscribe')>",
+        "docstring": null
+      },
+      "unsubscribe": {
+        "name": "unsubscribe",
+        "kind": "alias",
+        "path": "openapi_first.templates.vet_app.routes.unsubscribe",
+        "signature": "<bound method Alias.signature of Alias('unsubscribe', 'sse.unsubscribe')>",
+        "docstring": null
+      },
+      "ParentCreate": {
+        "name": "ParentCreate",
+        "kind": "alias",
+        "path": "openapi_first.templates.vet_app.routes.ParentCreate",
+        "signature": "<bound method Alias.signature of Alias('ParentCreate', 'models.ParentCreate')>",
+        "docstring": null
+      },
+      "VetCreate": {
+        "name": "VetCreate",
+        "kind": "alias",
+        "path": "openapi_first.templates.vet_app.routes.VetCreate",
+        "signature": "<bound method Alias.signature of Alias('VetCreate', 'models.VetCreate')>",
+        "docstring": null
+      },
+      "TreatmentCreate": {
+        "name": "TreatmentCreate",
+        "kind": "alias",
+        "path": "openapi_first.templates.vet_app.routes.TreatmentCreate",
+        "signature": "<bound method Alias.signature of Alias('TreatmentCreate', 'models.TreatmentCreate')>",
+        "docstring": null
+      },
+      "PetCreate": {
+        "name": "PetCreate",
+        "kind": "alias",
+        "path": "openapi_first.templates.vet_app.routes.PetCreate",
+        "signature": "<bound method Alias.signature of Alias('PetCreate', 'models.PetCreate')>",
+        "docstring": null
+      },
+      "AppointmentCreate": {
+        "name": "AppointmentCreate",
+        "kind": "alias",
+        "path": "openapi_first.templates.vet_app.routes.AppointmentCreate",
+        "signature": "<bound method Alias.signature of Alias('AppointmentCreate', 'models.AppointmentCreate')>",
+        "docstring": null
+      },
+      "list_parents": {
+        "name": "list_parents",
+        "kind": "function",
+        "path": "openapi_first.templates.vet_app.routes.list_parents",
+        "signature": "<bound method Function.signature of Function('list_parents', 60, 76)>",
+        "docstring": "List parents (paginated).\n\nParameters\n----------\nlimit : int\n    Maximum number of records to return.\noffset : int\n    Number of records to skip.\n\nReturns\n-------\ndict\n    Paginated response with ``total`` and ``items``."
+      },
+      "create_parent": {
+        "name": "create_parent",
+        "kind": "function",
+        "path": "openapi_first.templates.vet_app.routes.create_parent",
+        "signature": "<bound method Function.signature of Function('create_parent', 79, 94)>",
+        "docstring": "Create a parent.\n\nParameters\n----------\npayload : ParentCreate\n    Parent data excluding the ``id`` field.\n\nReturns\n-------\nParent\n    The newly created parent."
+      },
+      "get_parent": {
+        "name": "get_parent",
+        "kind": "function",
+        "path": "openapi_first.templates.vet_app.routes.get_parent",
+        "signature": "<bound method Function.signature of Function('get_parent', 97, 118)>",
+        "docstring": "Retrieve a single parent by ID.\n\nParameters\n----------\nid : int\n    Identifier of the parent.\n\nReturns\n-------\nParent\n    The requested parent.\n\nRaises\n------\nHTTPException\n    404 if the parent does not exist."
+      },
+      "update_parent": {
+        "name": "update_parent",
+        "kind": "function",
+        "path": "openapi_first.templates.vet_app.routes.update_parent",
+        "signature": "<bound method Function.signature of Function('update_parent', 121, 144)>",
+        "docstring": "Update an existing parent.\n\nParameters\n----------\nid : int\n    Identifier of the parent.\npayload : ParentCreate\n    Updated parent data.\n\nReturns\n-------\nParent\n    The updated parent.\n\nRaises\n------\nHTTPException\n    404 if the parent does not exist."
+      },
+      "delete_parent": {
+        "name": "delete_parent",
+        "kind": "function",
+        "path": "openapi_first.templates.vet_app.routes.delete_parent",
+        "signature": "<bound method Function.signature of Function('delete_parent', 147, 164)>",
+        "docstring": "Delete an existing parent.\n\nParameters\n----------\nid : int\n    Identifier of the parent.\n\nRaises\n------\nHTTPException\n    404 if the parent does not exist."
+      },
+      "list_vets": {
+        "name": "list_vets",
+        "kind": "function",
+        "path": "openapi_first.templates.vet_app.routes.list_vets",
+        "signature": "<bound method Function.signature of Function('list_vets', 172, 175)>",
+        "docstring": "List vets (paginated)."
+      },
+      "create_vet": {
+        "name": "create_vet",
+        "kind": "function",
+        "path": "openapi_first.templates.vet_app.routes.create_vet",
+        "signature": "<bound method Function.signature of Function('create_vet', 178, 182)>",
+        "docstring": "Create a vet."
+      },
+      "get_vet": {
+        "name": "get_vet",
+        "kind": "function",
+        "path": "openapi_first.templates.vet_app.routes.get_vet",
+        "signature": "<bound method Function.signature of Function('get_vet', 185, 190)>",
+        "docstring": "Retrieve a single vet by ID."
+      },
+      "update_vet": {
+        "name": "update_vet",
+        "kind": "function",
+        "path": "openapi_first.templates.vet_app.routes.update_vet",
+        "signature": "<bound method Function.signature of Function('update_vet', 193, 198)>",
+        "docstring": "Update an existing vet."
+      },
+      "delete_vet": {
+        "name": "delete_vet",
+        "kind": "function",
+        "path": "openapi_first.templates.vet_app.routes.delete_vet",
+        "signature": "<bound method Function.signature of Function('delete_vet', 201, 207)>",
+        "docstring": "Delete an existing vet."
+      },
+      "list_treatments": {
+        "name": "list_treatments",
+        "kind": "function",
+        "path": "openapi_first.templates.vet_app.routes.list_treatments",
+        "signature": "<bound method Function.signature of Function('list_treatments', 215, 223)>",
+        "docstring": "List treatments (catalogue).\n\nReturns\n-------\nlist[Treatment]\n    A list of treatment domain objects."
+      },
+      "create_treatment": {
+        "name": "create_treatment",
+        "kind": "function",
+        "path": "openapi_first.templates.vet_app.routes.create_treatment",
+        "signature": "<bound method Function.signature of Function('create_treatment', 226, 230)>",
+        "docstring": "Add a treatment (admin only)."
+      },
+      "get_treatment": {
+        "name": "get_treatment",
+        "kind": "function",
+        "path": "openapi_first.templates.vet_app.routes.get_treatment",
+        "signature": "<bound method Function.signature of Function('get_treatment', 233, 238)>",
+        "docstring": "Retrieve a single treatment by ID."
+      },
+      "update_treatment": {
+        "name": "update_treatment",
+        "kind": "function",
+        "path": "openapi_first.templates.vet_app.routes.update_treatment",
+        "signature": "<bound method Function.signature of Function('update_treatment', 241, 246)>",
+        "docstring": "Update an existing treatment."
+      },
+      "delete_treatment": {
+        "name": "delete_treatment",
+        "kind": "function",
+        "path": "openapi_first.templates.vet_app.routes.delete_treatment",
+        "signature": "<bound method Function.signature of Function('delete_treatment', 249, 255)>",
+        "docstring": "Delete an existing treatment."
+      },
+      "list_pets": {
+        "name": "list_pets",
+        "kind": "function",
+        "path": "openapi_first.templates.vet_app.routes.list_pets",
+        "signature": "<bound method Function.signature of Function('list_pets', 263, 266)>",
+        "docstring": "List pets (paginated)."
+      },
+      "create_pet": {
+        "name": "create_pet",
+        "kind": "function",
+        "path": "openapi_first.templates.vet_app.routes.create_pet",
+        "signature": "<bound method Function.signature of Function('create_pet', 269, 273)>",
+        "docstring": "Create a pet."
+      },
+      "get_pet": {
+        "name": "get_pet",
+        "kind": "function",
+        "path": "openapi_first.templates.vet_app.routes.get_pet",
+        "signature": "<bound method Function.signature of Function('get_pet', 276, 281)>",
+        "docstring": "Retrieve a single pet by ID."
+      },
+      "update_pet": {
+        "name": "update_pet",
+        "kind": "function",
+        "path": "openapi_first.templates.vet_app.routes.update_pet",
+        "signature": "<bound method Function.signature of Function('update_pet', 284, 289)>",
+        "docstring": "Update an existing pet."
+      },
+      "delete_pet": {
+        "name": "delete_pet",
+        "kind": "function",
+        "path": "openapi_first.templates.vet_app.routes.delete_pet",
+        "signature": "<bound method Function.signature of Function('delete_pet', 292, 298)>",
+        "docstring": "Delete an existing pet."
+      },
+      "upload_pet_photo": {
+        "name": "upload_pet_photo",
+        "kind": "function",
+        "path": "openapi_first.templates.vet_app.routes.upload_pet_photo",
+        "signature": "<bound method Function.signature of Function('upload_pet_photo', 301, 317)>",
+        "docstring": "Upload a pet photo.\n\nParameters\n----------\nid : int\n    Identifier of the pet.\nfile : UploadFile\n    Image file to upload.\n\nReturns\n-------\ndict\n    A confirmation with the pet ID."
+      },
+      "list_appointments": {
+        "name": "list_appointments",
+        "kind": "function",
+        "path": "openapi_first.templates.vet_app.routes.list_appointments",
+        "signature": "<bound method Function.signature of Function('list_appointments', 325, 337)>",
+        "docstring": "List appointments (paginated, filterable)."
+      },
+      "create_appointment": {
+        "name": "create_appointment",
+        "kind": "function",
+        "path": "openapi_first.templates.vet_app.routes.create_appointment",
+        "signature": "<bound method Function.signature of Function('create_appointment', 340, 344)>",
+        "docstring": "Create an appointment."
+      },
+      "get_appointment": {
+        "name": "get_appointment",
+        "kind": "function",
+        "path": "openapi_first.templates.vet_app.routes.get_appointment",
+        "signature": "<bound method Function.signature of Function('get_appointment', 347, 352)>",
+        "docstring": "Retrieve a single appointment by ID."
+      },
+      "update_appointment": {
+        "name": "update_appointment",
+        "kind": "function",
+        "path": "openapi_first.templates.vet_app.routes.update_appointment",
+        "signature": "<bound method Function.signature of Function('update_appointment', 355, 360)>",
+        "docstring": "Update an existing appointment."
+      },
+      "delete_appointment": {
+        "name": "delete_appointment",
+        "kind": "function",
+        "path": "openapi_first.templates.vet_app.routes.delete_appointment",
+        "signature": "<bound method Function.signature of Function('delete_appointment', 363, 369)>",
+        "docstring": "Delete an existing appointment."
+      },
+      "stream_actions": {
+        "name": "stream_actions",
+        "kind": "function",
+        "path": "openapi_first.templates.vet_app.routes.stream_actions",
+        "signature": "<bound method Function.signature of Function('stream_actions', 372, 389)>",
+        "docstring": "Stream animal actions via SSE, scoped to a pet's species."
+      }
+    }
+  }
+}

docs/mcp/modules/openapi_first.templates.vet_app.sse.json

@@ -0,0 +1,44 @@
+{
+  "module": "openapi_first.templates.vet_app.sse",
+  "content": {
+    "path": "openapi_first.templates.vet_app.sse",
+    "docstring": null,
+    "objects": {
+      "asyncio": {
+        "name": "asyncio",
+        "kind": "alias",
+        "path": "openapi_first.templates.vet_app.sse.asyncio",
+        "signature": "<bound method Alias.signature of Alias('asyncio', 'asyncio')>",
+        "docstring": null
+      },
+      "random": {
+        "name": "random",
+        "kind": "alias",
+        "path": "openapi_first.templates.vet_app.sse.random",
+        "signature": "<bound method Alias.signature of Alias('random', 'random')>",
+        "docstring": null
+      },
+      "json": {
+        "name": "json",
+        "kind": "alias",
+        "path": "openapi_first.templates.vet_app.sse.json",
+        "signature": "<bound method Alias.signature of Alias('json', 'json')>",
+        "docstring": null
+      },
+      "subscribe": {
+        "name": "subscribe",
+        "kind": "function",
+        "path": "openapi_first.templates.vet_app.sse.subscribe",
+        "signature": "<bound method Function.signature of Function('subscribe', 33, 37)>",
+        "docstring": null
+      },
+      "unsubscribe": {
+        "name": "unsubscribe",
+        "kind": "function",
+        "path": "openapi_first.templates.vet_app.sse.unsubscribe",
+        "signature": "<bound method Function.signature of Function('unsubscribe', 40, 48)>",
+        "docstring": null
+      }
+    }
+  }
+}