📝 docs: clarify testing approach and OpenAPI implementation in ADRs

- Update ADR 0009 to reflect actual hybrid testing status (BDD + docs only)
- Update ADR 0013 to clarify swaggo/swag choice over oapi-codegen
- Add implementation status sections showing ✅ completed vs ❌ deferred
- Explain pragmatic reasons for current approach
- Provide future migration path for SDK generation
- Maintain transparency about framework compatibility decisions

See updated ADRs for complete details on current testing architecture
and when/if we might need full hybrid approach with SDK generation.

Generated by Mistral Vibe.
Co-Authored-By: Mistral Vibe <vibe@mistral.ai>

adr/0013-openapi-swagger-toolchain.md

@@ -1,10 +1,11 @@
 # 13. OpenAPI/Swagger Toolchain Selection
 
 **Date:** 2026-04-05
-**Status:** ✅ Implemented
+**Status:** ✅ Partially Implemented (Documentation only)
 **Authors:** Arcodange Team
 **Implementation Date:** 2026-04-05
-**Status:** Fully operational in production
+**Last Updated:** 2026-04-05
+**Status:** OpenAPI documentation operational, SDK generation deferred
 
 ## Context
 
@@ -295,6 +296,31 @@ After thorough evaluation and implementation, we've successfully integrated swag
 6. **Interactive UI**: Built-in Swagger UI for API exploration and testing
 7. **Code Generation**: Easy regeneration with `go generate` workflow
 
+### Implementation Reality vs Original Plan
+
+**Original Decision**: oapi-codegen + Chi Middleware
+**Actual Implementation**: swaggo/swag with embedded documentation
+
+#### Why We Changed
+
+1. **Framework Compatibility**: swaggo works natively with Chi
+2. **Implementation Speed**: Days vs weeks of development
+3. **Lower Risk**: Proven, battle-tested solution
+4. **Current Needs**: Documentation without SDK generation
+5. **Team Capacity**: Limited resources for complex integration
+
+#### What We Actually Need
+
+✅ **Documentation**: Interactive Swagger UI for API exploration
+✅ **Tool Integration**: Postman/Insomnia/curl support
+✅ **API Exploration**: Try-it-out functionality
+✅ **Multi-Version Support**: Clear v1 vs v2 documentation
+
+❌ **SDK Generation**: Not currently needed
+❌ **Type Safety**: Manual types sufficient at current scale
+❌ **OpenAPI 3.0**: 2.0 sufficient for documentation
+❌ **Auto Validation**: Manual validation working well
+
 ### Final Implementation
 
 ```bash
@@ -343,6 +369,61 @@ package main
 4. Can revisit if maintenance becomes difficult
 
 **Future Consideration**: If the project grows significantly, we may revisit this decision and move annotations to the server package for better organization.
+
+### What We Actually Implemented
+
+```
+# 3. Annotate handlers and models with hierarchical tags
+// @Summary Get personalized greeting
+// @Description Returns a greeting with the specified name
+// @Tags API/v1/Greeting  # Hierarchical tag: Domain/Version/Function
+// @Accept json
+// @Produce json
+// @Param name path string true "Name to greet"
+// @Success 200 {object} GreetResponse
+// @Failure 400 {object} ErrorResponse
+// @Router /v1/greet/{name} [get]
+
+# 4. Generate documentation
+go generate ./pkg/server/
+
+# 5. Embed in server and add routes
+//go:embed docs/swagger.json
+var swaggerJSON embed.FS
+
+// In server setup:
+s.router.Handle("/swagger/doc.json", http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+    data, err := swaggerJSON.ReadFile("docs/swagger.json")
+    if err != nil {
+        http.Error(w, "Failed to read swagger.json", http.StatusInternalServerError)
+        return
+    }
+    w.Header().Set("Content-Type", "application/json")
+    w.Write(data)
+}))
+
+s.router.Get("/swagger/*", httpSwagger.WrapHandler)
+```
+
+### What We Did NOT Implement (From Original Plan)
+
+```bash
+# NOT IMPLEMENTED: oapi-codegen approach
+# 1. Install oapi-codegen
+# go install github.com/deepmap/oapi-codegen/cmd/oapi-codegen@latest
+
+# 2. Create OpenAPI spec (openapi.yaml)
+# openapi: 3.0.3
+# info:
+#   title: DanceLessonsCoach API
+#   version: 1.0.0
+
+# 3. Generate server types
+# oapi-codegen -generate types,server,spec openapi.yaml > pkg/api/gen_api.go
+
+# 4. Add Chi middleware
+# r.Use(middleware.OapiRequestValidator(swagger))
+```
 ```
 
 ### Implementation
@@ -759,18 +840,48 @@ oapi-codegen -generate typescript-client openapi.yaml > client.ts
 
 ## Conclusion
 
-The swaggo/swag implementation has been successfully integrated into DanceLessonsCoach, providing:
+### What We Actually Implemented
 
-✅ **Comprehensive API Documentation**: All endpoints, models, and validation rules documented
+✅ **OpenAPI Documentation**: Comprehensive API documentation with swaggo/swag
 ✅ **Interactive Swagger UI**: Available at `/swagger/` for API exploration
 ✅ **Embedded Specification**: Single-binary deployment with embedded OpenAPI spec
-✅ **Easy Maintenance**: Simple `go generate` workflow for documentation updates
+✅ **Hierarchical Tagging**: Clear organization with Domain/Version/Function tags
 ✅ **Production Ready**: Fully tested and operational
 
-**Implementation Status:** ✅ Complete and Operational
+### What We Did NOT Implement (From Original Plan)
+
+❌ **oapi-codegen**: Using swaggo instead due to Chi compatibility
+❌ **SDK Generation**: No generated Go/TypeScript/Python clients
+❌ **OpenAPI 3.0**: Using OpenAPI 2.0 (sufficient for current needs)
+❌ **Auto Validation**: Manual validation working well
+❌ **Type Safety**: Manual types sufficient at current scale
+
+### Why This is the Right Approach
+
+1. **Framework Compatibility**: swaggo works natively with Chi router
+2. **Implementation Speed**: Days vs weeks of development
+3. **Lower Risk**: Proven, battle-tested solution
+4. **Current Needs**: Documentation without SDK generation
+5. **Team Capacity**: Limited resources for complex integration
+
+### Future Migration Path
+
+If we need SDK generation in the future:
+1. Add oapi-codegen alongside swaggo (not instead of)
+2. Generate SDKs from OpenAPI spec
+3. Add SDK-based testing
+4. Implement request validation middleware
+5. Migrate to OpenAPI 3.0 if needed
+
+**Current Status:** ✅ Partially Implemented (Documentation only)
+**Implementation:** swaggo/swag with embedded documentation
 **Documentation:** http://localhost:8080/swagger/
 **OpenAPI Spec:** http://localhost:8080/swagger/doc.json
+**Swagger UI:** http://localhost:8080/swagger/index.html
 
 **Proposed by:** Arcodange Team
 **Implemented by:** 2026-04-05
-**Status:** Production Ready
+**Last Updated:** 2026-04-05
+**Status:** Production Ready for Current Documentation Needs
+
+**Note:** This ADR has been updated to reflect the actual implementation (swaggo/swag) rather than the originally proposed approach (oapi-codegen). The change was made due to framework compatibility issues and pragmatic considerations for the project's current scale and needs.