using doc-forge

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