Add implementation planning and architecture documents

IMPLEMENTATION_PLAN.md:
- Phase-by-phase implementation plan
- Success criteria for each phase
- Testing requirements
- Dependencies and prerequisites

CLEANUP_TODO.md:
- Architecture decision log
- Future considerations and trade-offs
- Migration path notes
- Technical debt tracking

These documents provide context for implementation decisions
and serve as a reference for future development.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

CLEANUP_TODO.md

@@ -0,0 +1,206 @@
+# Cleanup Todo: Chat Completions API Wrapper
+
+**Status**: CHANGED - Chat Completions is now a wrapper, not legacy code
+
+## New Architecture (As of 2025-12-06)
+
+Chat Completions API is now a **compatibility wrapper** around Responses API:
+- Maintains single source of truth (Responses API)
+- Converts Responses output to Chat Completions format
+- Embeds reasoning in `<think>` tags for Open WebUI
+- Provides backward compatibility
+
+## When to Consider Cleanup
+
+Only remove Chat Completions wrapper if **ALL** of these conditions are met:
+
+1. ✅ Open WebUI natively supports Responses API
+2. ✅ All other consumers migrated to `/v1/responses`
+3. ✅ No tools/clients require `/v1/chat/completions`
+4. ✅ Team consensus on removal
+
+**Current Status**: KEEP - Provides essential compatibility for Open WebUI
+
+---
+
+## Optional Removal Checklist
+
+### Phase 1: Verify All Consumers Migrated
+
+- [ ] Open WebUI using `/v1/responses` natively
+- [ ] No external tools using `/v1/chat/completions`
+- [ ] Check server logs for chat completions usage
+- [ ] Confirm with team/users
+
+### Phase 2: Deprecation Period
+
+- [ ] Add deprecation notice to `/v1/chat/completions` docs
+- [ ] Update OpenAPI/Swagger docs with deprecation warning
+- [ ] Log deprecation warnings on chat completions usage
+- [ ] Maintain for at least one version cycle
+
+### Phase 3: Code Removal (If Approved)
+
+#### Remove Chat Domain
+
+- [ ] Delete `src/chat/` directory
+  - [ ] `src/chat/router.py`
+  - [ ] `src/chat/service.py`
+  - [ ] `src/chat/schemas.py`
+  - [ ] `src/chat/constants.py`
+  - [ ] Keep `src/chat/__init__.py` if needed for imports
+
+#### Update Main Application
+
+- [ ] Edit `src/main.py`
+  - [ ] Remove `from src.chat.router import router as chat_router`
+  - [ ] Remove `app.include_router(chat_router, prefix=config.API_PREFIX)`
+
+#### Remove Tests
+
+- [ ] Delete `tests/chat/` directory
+- [ ] Remove chat fixtures from `tests/conftest.py`
+
+### Phase 4: Documentation Updates
+
+- [ ] Update README.md
+  - [ ] Remove `/v1/chat/completions` examples
+  - [ ] Mark as "Responses API only"
+  - [ ] Add migration guide link
+
+- [ ] Update CHANGELOG.md
+  ```markdown
+  ## [Unreleased]
+
+  ### Removed
+  - Chat Completions API wrapper (deprecated in v0.X.0)
+  - All clients must now use POST /v1/responses
+
+  ### Migration
+  - See MIGRATION.md for Responses API format
+  ```
+
+- [ ] Create MIGRATION.md
+  - [ ] Show before/after examples
+  - [ ] Explain `<think>` tags vs proper reasoning items
+  - [ ] Conversion guide
+
+---
+
+## Current Recommended Action
+
+**DO NOT REMOVE** - The Chat Completions wrapper serves these purposes:
+
+1. **Open WebUI Compatibility** - Provides `<think>` tag format
+2. **Backward Compatibility** - Supports existing clients
+3. **Migration Path** - Smooth transition to Responses API
+4. **Minimal Cost** - Thin wrapper, low maintenance
+
+### Documentation Instead of Removal
+
+Update documentation to clarify architecture:
+
+- [x] Chat Completions is a wrapper around Responses API
+- [ ] Document wrapper behavior in README.md
+- [ ] Explain `<think>` tag conversion in AGENTS.md
+- [ ] Note single source of truth (Responses API)
+
+---
+
+## Alternative: Keep as Compatibility Layer
+
+**Recommended approach**: Keep Chat Completions as permanent compatibility layer
+
+### Benefits
+
+- ✅ Supports multiple client types
+- ✅ Single codebase maintains both formats
+- ✅ No breaking changes for users
+- ✅ Minimal maintenance burden
+
+### Maintenance
+
+- Update wrapper when Responses API changes
+- Keep tests for both endpoints
+- Document as compatibility layer
+- Monitor usage metrics
+
+---
+
+## Git Commit (If Documenting, Not Removing)
+
+```bash
+git add -A
+git commit -m "Document Chat Completions as Responses API wrapper
+
+Update documentation to clarify that Chat Completions endpoint is a
+compatibility wrapper around Responses API, not legacy code.
+
+Architecture:
+- Single source of truth: Responses API
+- Chat Completions wraps Responses API
+- Converts reasoning to <think> tags for Open WebUI
+- Maintains backward compatibility
+
+Documentation Updates:
+- README.md: Explain wrapper architecture
+- AGENTS.md: Document conversion behavior
+- CLEANUP_TODO.md: Update removal guidance
+
+Status: Chat Completions is a supported compatibility layer
+
+🤖 Generated with [Claude Code](https://claude.com/claude-code)
+
+Co-Authored-By: Claude <noreply@anthropic.com>"
+```
+
+---
+
+## Decision Criteria
+
+Ask these questions before removing:
+
+1. **Is anyone using `/v1/chat/completions`?**
+   - Check server logs
+   - Survey users/team
+   - Monitor for 30+ days
+
+2. **Does Open WebUI support Responses API natively?**
+   - Version with native support released?
+   - Tested and verified working?
+   - Migration path clear?
+
+3. **Is there value in multiple formats?**
+   - Some clients prefer Chat Completions
+   - Easier integration for simple use cases
+   - Lower barrier to entry
+
+4. **What's the maintenance cost?**
+   - Currently: LOW (thin wrapper)
+   - If removed: Users must update clients
+   - Cost/benefit analysis
+
+---
+
+## Conclusion
+
+**Current Recommendation**: **KEEP** Chat Completions wrapper
+
+- Provides value (Open WebUI compatibility)
+- Low maintenance cost
+- Enables smooth migration
+- No compelling reason to remove
+
+**Revisit** when:
+- Open WebUI natively supports Responses API
+- Usage metrics show zero chat completions traffic
+- Team decides compatibility layer not needed
+
+---
+
+## Notes
+
+- This replaces the original "remove chat completions" plan
+- Architecture has evolved: wrapper is intentional, not legacy
+- Removal is now **optional** and **conditional**
+- Focus on documentation, not deletion