backend-api-compatibility

name	backend-api-compatibility
description	Use when changing or reviewing Nevermind desktop/backend contracts - Astro API routes used by desktop, Electron backend fetches, auth/device login, token revoke, active-model descriptors, AI proxy routes, billing/rate-limit/error shapes, compatibility manifests, feature flags, backend deploy policy, desktop release/update interactions, or any request about keeping frontend and backend in sync.

Backend API Compatibility

Nevermind's Electron desktop app ships on tagged releases while the backend may deploy continuously. Treat the backend as a backwards-compatible service for installed desktop clients.

Start here

1. Read docs/backend-api-compatibility.md.
2. Map both sides of the contract before changing code:
   • Desktop callers in src/app/electron/nevermind-auth.ts, src/app/electron/ai.ts, and related main-process flows.
   • Backend routes in src/backend/src/pages/api/** and shared backend libraries in src/backend/src/lib/**.
3. Identify the change type: additive, feature-gated, compatibility shim, API-major change, or intentional unsupported-client block.
4. Prefer compatibility gates and additive fields over lockstep frontend/backend releases.

Contract rules

• /api/v1/* is stable for supported desktop clients.
• Missing optional desktop headers must not break older clients.
• Unknown JSON fields must be safe for older desktop clients.
• Error shapes, auth semantics, billing behavior, and streaming semantics are part of the contract.
• Backend request identity headers are observability and compatibility metadata, never authentication.
• A backend-only change must not require a not-yet-installed desktop release unless it is gated or returns an explicit update requirement.

Required review questions