diff --git a/AGENTS.md b/AGENTS.md
index 500bc5fcb..56d6f5c76 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -23,7 +23,7 @@
 - Never remove or downgrade code to fix type errors from outdated deps; upgrade the dep instead.
 - Use only erasable TypeScript syntax (Node strip-only mode) in code checked by the root config (`packages/*/src`, `packages/*/test`, `packages/coding-agent/examples`): no parameter properties, `enum`, `namespace`/`module`, `import =`, `export =`, or other constructs needing JS emit. Use explicit fields with constructor assignments.
 - Always ask before removing functionality or code that appears intentional.
-- Never break public APIs outside a major release. Keep the old form working next to the new one and mark it `// remove-in-next-major: <what and why>`. If that is not possible, ask first.
+- Never break public APIs (exports, types, CLI flags, file formats) outside a major release; settings and UI may change. Keep the old form working next to the new one, mark it `// remove-in-next-major: <what and why>`, and add `/** @deprecated Use <replacement>. */` to exported symbols. If that is not possible, ask first.
 - Never hardcode key checks (e.g. `matchesKey(keyData, "ctrl+x")`). Add defaults to `DEFAULT_EDITOR_KEYBINDINGS` or `DEFAULT_APP_KEYBINDINGS` so they stay configurable.
 - Never modify `packages/ai/src/models.generated.ts` directly; update the catalog definitions in `packages/ai/catalog/` instead (see its README), then regenerate. Including the resulting `models.generated.ts` diff is always OK, even if regeneration includes unrelated upstream model metadata changes. The generated model data in `packages/ai/src/providers/data/` is gitignored: never stage it, and don't look for it in git history.