# Upgrade Guide

## Standard Upgrade Path

1. Read the release notes for your current and target versions.
2. Run `logos-adk upgrade plan --from-version <current> --to-version <target>`.
3. Run `logos-adk upgrade checklist`.
4. Run `logos-adk storage upgrade-check` for every persistence backend.
5. Apply schema upgrades with `logos-adk upgrade migrate-storage`.
6. Deploy to staging and run the full test and smoke suite.
7. Validate RBAC, workspace isolation, observability dashboards, and alert rules.
8. Roll out gradually and monitor error rates, latency, and dead-letter queues.

## Import Stability

For external applications, prefer imports from [`logos_adk`](../logos_adk/__init__.py)
and the modules listed in [`logos_adk.version`](../logos_adk/version.py). Avoid
importing private implementation modules directly.

## Long-Running Services

- rotate API keys before the upgrade window when possible
- ensure idempotency keys are preserved across retries
- verify dead-letter backlog is empty or understood before rollout
