📝 docs: add comprehensive version management and CLI documentation

adr/0013-openapi-swagger-toolchain.md

@@ -309,6 +309,44 @@ go install github.com/swaggo/swag/cmd/swag@latest
 // @BasePath /api
 package main
 
+### Annotation Placement Considerations
+
+**Current Approach**: Annotations in `cmd/server/main.go`
+
+**Pros**:
+- Follows Go community conventions
+- Works seamlessly with swaggo
+- Clear entry point for API documentation
+
+**Cons**:
+- Mixes API metadata with main package
+- Less separation of concerns
+
+**Alternative**: Annotations in `pkg/server/server.go`
+
+**Pros**:
+- Better organization (all server code together)
+- More logical separation
+- Easier maintenance
+
+**Cons**:
+- May require swag configuration changes
+- Less conventional
+- Potential tooling issues
+
+**Decision**: Keep annotations in `cmd/server/main.go` for now
+
+**Rationale**:
+1. Follows established community patterns
+2. Works reliably with current toolchain
+3. Minimizes risk of breaking changes
+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.
+```
+
+### Implementation
+
 # 3. Annotate handlers and models with hierarchical tags
 // @Summary Get personalized greeting
 // @Description Returns a greeting with the specified name