# Backend API Compatibility

> 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.

- Skill: `pablopunk/backend-api-compatibility` (Agent Skill)
- Install (CLI): `npx skillmds@latest add pablopunk/backend-api-compatibility`
- Raw SKILL.md: https://api.skillmd.com/api/skills/pablopunk/backend-api-compatibility/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: pablopunk (https://skillmd.com/u/pablopunk)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/pablopunk/backend-api-compatibility

---


# 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

- Which released desktop versions can call this route?
- What happens if the desktop does not send the new field/header?
- What happens if the backend returns an unknown field/error?
- Is the change safe under continuous backend deploys?
- Does the user get a palette-safe update/account action if the client is unsupported?
- Do logs identify desktop version, API contract version, route, status, and request ID?

## Verification expectations

For implementation work, add or update contract coverage for:

- compatibility manifest shape
- unsupported-client response shape
- device auth initiation/exchange when changed
- token revoke when changed
- active-model descriptor shape when changed
- AI proxy success/error/rate-limit/billing responses when changed
- streaming response behavior when changed

Run package commands through `mise exec pnpm` as required by the repo guidelines.

## Output expectations

When reporting compatibility work, include:

- affected desktop callers and backend routes
- whether the change is additive, gated, breaking, or a shim
- supported desktop versions considered
- contract tests or manual verification performed
- residual rollout or sunset risks