Dx improvements

CHANGELOG.md

@@ -0,0 +1,42 @@
+# Changelog
+
+All notable changes to the ResolveKit Backend will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] - 2026-04-30
+
+### Added
+- FastAPI agent service with WebSocket event streaming
+- Knowledge bases service with document ingestion, embedding, and search
+- Next.js admin dashboard with full app management UI
+- Dashboard API routes () for programmatic access
+- OpenAPI specs for agent, dashboard, and knowledge_bases APIs
+- Docker Compose configs for local and production deployment
+- Caddy reverse proxy configuration
+- Alembic database migrations (21 migrations)
+- Organization management with invitations and roles
+- LLM provider profiles with encrypted secrets
+- Chat theme customization per app
+- Chat localization support (multi-language)
+- Function registry with allowlist scoping
+- Playbook system for structured agent flows
+- Usage tracking and cost calculation
+- Audit event logging
+- Session reconnect with ticket-based auth
+- Agent config with scope mode (strict/permissive)
+- Pending tool results for approval workflows
+- Turn state service for agent context persistence
+
+### Changed
+- Migrated to uv for Python dependency management
+- Dashboard split into separate Next.js app with API routes
+- Knowledge bases separated into dedicated service
+
+### Security
+- Fernet encryption for provider profile secrets
+- SDK client token auth with JWT
+- CORS configuration for dashboard origins
+- Rate limiting on auth endpoints
+

COMPATIBILITY.md

@@ -0,0 +1,53 @@
+---
+title: "ResolveKit — Version Compatibility Matrix"
+created: 2026-04-30
+---
+
+# ResolveKit — Version Compatibility Matrix
+
+This document tracks which SDK versions are compatible with which backend versions.
+
+## Compatibility Table
+
+| Backend Version | iOS SDK | Android SDK | Web SDK | Notes |
+| --- | --- | --- | --- | --- |
+| `1.0.0` | `1.4.2` | `1.0.1` | N/A | Initial OSS release |
+| `1.0.0` | `1.4.1` | `1.0.0` | N/A | Compatible with minor SDK patches |
+| `0.9.x` | `1.3.0` | `0.9.x` | N/A | Pre-release, not recommended for production |
+
+## Versioning Policy
+
+- **Backend** uses Semantic Versioning (`MAJOR.MINOR.PATCH`)
+- **SDKs** use independent versioning but maintain backward compatibility within major versions
+- **Breaking changes** in backend API will bump the major version
+- SDKs are backward compatible with older backend versions unless a new protocol feature is required
+
+## Protocol Version
+
+The ResolveKit protocol version is tied to the major backend version:
+
+- **Protocol v1** (Backend `1.x`): Current stable protocol
+  - HTTP/3-first session event stream
+  - WebSocket for real-time events
+  - JSON Schema for tool definitions
+  - JWT-based auth
+
+## Upgrade Guide
+
+### Upgrading Backend
+1. Review the [CHANGELOG.md](CHANGELOG.md) for breaking changes
+2. Run database migrations: `uv run alembic upgrade head`
+3. Update `.env` if new variables are required
+4. Restart services: `docker compose up -d`
+
+### Upgrading SDKs
+1. Check compatibility table above
+2. Update your dependency version in Package.swift (iOS) or build.gradle.kts (Android)
+3. Review the SDK's CHANGELOG.md for API changes
+4. Test with your app's existing integration
+
+## Deprecation Policy
+
+- Minor versions are supported for 6 months after a new minor release
+- Major versions are supported for 12 months after a new major release
+- Deprecated versions receive security patches but no new features