using doc-forge (#1)

Reviewed-on: #1
Co-authored-by: Vishesh 'ironeagle' Bangotra <aetoskia@gmail.com>
Co-committed-by: Vishesh 'ironeagle' Bangotra <aetoskia@gmail.com>

openapi_first/__init__.py

@@ -205,6 +205,27 @@ Design Guarantees
 
 FastAPI OpenAPI First favors correctness, explicitness, and contract
 enforcement over convenience shortcuts.
+
+## Core Philosophy
+
+`FastAPI OpenAPI First` operates on the **Contract-as-Code** principle:
+
+1. **Spec-Driven Routing**: The OpenAPI document *is* the router. Code only exists to fulfill established contracts.
+2. **Startup Fail-Fast**: Binding mismatches (missing handlers or extra operations) are detected during app initialization, not at runtime.
+3. **Decoupled Symmetry**: The same specification drives both the FastAPI server and the `httpx`-based client, ensuring type-safe communication.
+
+## Documentation Design
+
+Follow these "AI-Native" docstring principles to maximize developer and agent productivity:
+
+### For Humans
+- **Logical Grouping**: Document the Loader, Binder, and Client as distinct infrastructure layers.
+- **Spec Snippets**: Always include the corresponding OpenAPI YAML/JSON snippet alongside Python examples.
+
+### For LLMs
+- **Full Path Linking**: Refer to cross-module dependencies using their full dotted paths (e.g., `openapi_first.loader.load_openapi`).
+- **Complete Stubs**: Maintain high-fidelity `.pyi` stubs for all public interfaces to provide an optimized machine-context.
+- **Traceable Errors**: Use specific `: description` pairs in `Raises` blocks to allow agents to accurately map errors to spec violations.
 """
 
 from . import app

openapi_first/__init__.pyi

@@ -0,0 +1,7 @@
+from . import app as app
+from . import binder as binder
+from . import loader as loader
+from . import client as client
+from . import errors as errors
+
+__all__ = ["app", "binder", "loader", "client", "errors"]

openapi_first/app.pyi

@@ -0,0 +1,5 @@
+from fastapi import FastAPI
+from typing import Any
+
+class OpenAPIFirstApp(FastAPI):
+    def __init__(self, *, openapi_path: str, routes_module: Any, **fastapi_kwargs: Any) -> None: ...

openapi_first/binder.pyi

@@ -0,0 +1,4 @@
+from typing import Any, Dict
+from fastapi import FastAPI
+
+def bind_routes(app: FastAPI, spec: Dict[str, Any], routes_module: Any) -> None: ...

openapi_first/client.pyi

@@ -0,0 +1,13 @@
+from typing import Any, Callable, Dict, Optional
+import httpx
+from .errors import OpenAPIFirstError
+
+class OpenAPIClientError(OpenAPIFirstError): ...
+
+class OpenAPIClient:
+    spec: Dict[str, Any]
+    base_url: str
+    client: httpx.Client
+    def __init__(self, spec: Dict[str, Any], base_url: Optional[str] = ..., client: Optional[httpx.Client] = ...) -> None: ...
+    def __getattr__(self, name: str) -> Callable[..., httpx.Response]: ...
+    def operations(self) -> Dict[str, Callable[..., httpx.Response]]: ...

openapi_first/errors.pyi

@@ -0,0 +1,6 @@
+from typing import Optional
+
+class OpenAPIFirstError(Exception): ...
+
+class MissingOperationHandler(OpenAPIFirstError):
+    def __init__(self, *, path: str, method: str, operation_id: Optional[str] = ...) -> None: ...

openapi_first/loader.pyi

@@ -0,0 +1,8 @@
+from pathlib import Path
+from typing import Any, Dict, Union
+
+from .errors import OpenAPIFirstError
+
+class OpenAPISpecLoadError(OpenAPIFirstError): ...
+
+def load_openapi(path: Union[str, Path]) -> Dict[str, Any]: ...