docs: document API deprecation process (closes #75)

README.md

@@ -240,6 +240,30 @@ The desktop app uses [pywebview](https://pywebview.flowrl.com/) to render the Fl
 - **Frontend:** Vanilla HTML/CSS/JS (no npm, no build step)
 - **PDF:** fpdf2
 
+## Versioning
+
+This project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html) (`MAJOR.MINOR.PATCH`).
+
+**Pre-1.0 stability (current):** The project is at `0.x.y`. During this phase:
+
+- **Minor version bumps (`0.x` → `0.x+1`)** may include breaking changes to the HTTP API, CLI flags, or exported file formats. Consumers of the `/api/*` endpoints or the `cursor-chat-export` CLI should review the changelog before upgrading.
+- **Patch version bumps (`0.x.y` → `0.x.y+1`)** are backward-compatible bug fixes only.
+
+**What constitutes a breaking change:**
+
+| Surface | Breaking examples |
+|---|---|
+| HTTP API | Removing or renaming an endpoint; changing the JSON schema of a response in a non-additive way |
+| CLI (`cursor-chat-export`) | Removing or renaming a flag; changing default output structure |
+| Export formats | Removing YAML frontmatter fields; changing the zip directory layout |
+| Python package | Removing a public symbol from an importable module |
+
+Adding new optional fields to JSON responses, adding new CLI flags with sensible defaults, or adding new export-format sections are *not* considered breaking.
+
+A complete history of changes is maintained in **[CHANGELOG.md](CHANGELOG.md)** following the [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) format.
+
+When an API surface is scheduled for removal, follow the process in **[docs/API_DEPRECATION.md](docs/API_DEPRECATION.md)** (response headers, changelog entries, minimum notice period).
+
 ## License
 
 This project is licensed under the [Boost Software License 1.0](https://www.boost.org/LICENSE_1_0.txt).

docs/API_DEPRECATION.md

@@ -0,0 +1,41 @@
+# API Deprecation Policy
+
+How the HTTP API (`/api/*`), CLI flags (`cursor-chat-export`), and shared JSON response fields are deprecated and removed. Complements the [Versioning](../README.md#versioning) section and [CHANGELOG.md](../CHANGELOG.md).
+
+## Pre-1.0 posture
+
+While the project is at `0.x.y`, **breaking changes may land in any minor release** without a prior deprecation cycle. Deprecations are still recorded in the changelog when practicable, but there is no guarantee of advance notice before removal. After `1.0.0`, the workflow below applies in full.
+
+## Deprecation workflow
+
+When an endpoint, parameter, response field, or CLI flag is scheduled for removal:
+
+1. **CHANGELOG** — Add an entry under `### Deprecated` naming the surface, its replacement (if any), and the planned removal version.
+2. **Response headers** — Deprecated HTTP endpoints and parameters emit a `Deprecation` header on every affected response (see [Header format](#header-format)).
+3. **Server log** — Route handlers log `logging.warning()` with the deprecated symbol and recommended replacement.
+4. **Removal** — Remove no earlier than **one minor version** after the deprecation was announced (e.g. deprecated in `1.2.0`, removable from `1.4.0`). Document under `### Removed` in the changelog.
+
+## Header format
+
+Deprecated HTTP routes and query parameters set:
+
+```http
+Deprecation: true; sunset=2026-09-01
+```
+
+- `sunset` — ISO 8601 calendar date (UTC) when removal is scheduled.
+- Optionally add `link="<url>"` pointing to the changelog entry or migration notes.
+
+Clients should treat any `Deprecation: true` response as a signal to migrate before the sunset date.
+
+## Surfaces covered
+
+| Surface | Signals |
+|---------|---------|
+| HTTP endpoint or parameter | `Deprecation` header, changelog entry, server log |
+| JSON response field | Changelog entry; field remains until removal |
+| CLI flag | `(deprecated)` in `--help`, changelog entry |
+
+## Removal documentation
+
+Removals go under `### Removed` in [CHANGELOG.md](../CHANGELOG.md): what was removed, which version deprecated it, and the migration path.

pyproject.toml

@@ -79,6 +79,7 @@ include = [
     "launcher.py",
     "requirements.txt",
     "README.md",
+    "docs/",
     "DEPLOYMENT.md",
     "LICENSE",
     "cursor-browser.spec",