fix: coderabbitai's findings.

Author: bradjin8

README.md

@@ -249,7 +249,7 @@ This project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html)
 **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.
+- **Patch version bumps (`0.x.y` → `0.x.y+1`)** are backward-compatible bug fixes only. Critical security fixes may break compatibility at any version with appropriate changelog notation.
 
 **What constitutes a breaking change:**
 
@@ -258,7 +258,8 @@ This project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html)
 | 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 |
+
+Internal Python modules are not a semver-governed library API for external importers.
 
 Adding new optional fields to JSON responses, adding new CLI flags with sensible defaults, or adding new export-format sections are *not* considered breaking.
 

docs/API_DEPRECATION.md

@@ -4,36 +4,48 @@ How the HTTP API (`/api/*`), CLI flags (`cursor-chat-export`), and shared JSON r
 
 ## 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.
+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. Pre-1.0, workflow steps 2–4 (CLI help text, response headers, server logs) are **encouraged but optional**; step 1 (changelog) applies when practicable. 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)). When the first endpoint is deprecated, implement this via a small shared Flask helper so handlers stay consistent with the policy.
-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.3.0`). Document under `### Removed` in the changelog.
+2. **CLI help** (flags only) — Add `(deprecated, use <replacement>)` to the flag's argparse help string.
+3. **Response headers** — Deprecated HTTP endpoints and parameters emit deprecation headers on every affected response (see [Header format](#header-format)). When the first endpoint is deprecated, implement via a small shared Flask helper so handlers stay consistent with the policy.
+4. **Server log** — Route handlers log `logging.warning()` with the deprecated symbol and recommended replacement.
+5. **Removal** — Remove no earlier than **one minor version** after the deprecation was announced (e.g. deprecated in `1.2.0`, removable from `1.3.0`). Document under `### Removed` in the changelog.
 
 ## Header format
 
-Deprecated HTTP routes and query parameters set:
+This project currently documents a **simplified custom format** for pre-1.0. It does not match [IETF `Deprecation`](https://datatracker.ietf.org/doc/html/draft-ietf-httpapi-deprecation-header) (HTTP-date value, not `true`) or [RFC 8594](https://www.rfc-editor.org/rfc/rfc8594) (separate `Sunset` and `Link` headers). Adopt the standards-aligned form below when the shared Flask helper lands or at `1.0.0`.
+
+**Current (custom, pre-1.0):**
 
 ```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.
+- `sunset=` — ISO 8601 calendar date (UTC) when removal is scheduled, embedded in the `Deprecation` value.
+
+**Target (standards-aligned)** — emit as **separate headers** from Flask:
+
+```http
+Deprecation: Tue, 01 Sep 2026 00:00:00 GMT
+Sunset: Tue, 01 Sep 2026 00:00:00 GMT
+Link: <https://github.com/cppalliance/cppa-cursor-browser/blob/HEAD/CHANGELOG.md>; rel="deprecation"
+```
+
+Migration notes use a separate **`Link`** header (RFC 8288), not a `link=` parameter on `Deprecation`.
 
-Clients should treat any `Deprecation: true` response as a signal to migrate before the sunset date.
+Clients should treat any deprecation signal as a prompt 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 |
+| HTTP endpoint or parameter | Deprecation headers, changelog entry, server log |
+| JSON response field | Changelog entry; field remains until removal (no in-band signal today; future: `X-Deprecated-Fields` header or `_deprecated` envelope key) |
 | CLI flag | `(deprecated)` in `--help`, changelog entry |
 
 ## Removal documentation