# API Stability

KiCad MCP Pro treats public MCP tools, resource URIs, prompt names, server profiles, environment variables, and documented CLI behavior as public API.

## Stability Levels

- **Stable:** documented behavior used by normal clients.
- **Experimental:** hidden unless explicitly enabled or marked experimental in tool metadata.
- **Internal:** helpers, modules, and implementation details not documented for clients.

## Deprecation Policy

Stable API removals require:

1. A deprecation note in docs or changelog.
2. Runtime or discovery-visible warning when practical.
3. At least two minor releases before removal.

Security fixes may bypass the full deprecation window when preserving behavior would put users at risk.

## Breaking Changes

Breaking changes require a PR label, changelog entry, migration note, and, for major public workflow changes, an RFC.

## Live-preview workflow stability

`sch_live_preview()` is a documented agent workflow surface, but clients must
separate stable workflow semantics from evolving implementation metadata.

Stable for client use:

- baseline, no-change, debounce-pending, changed, and rendered status concepts;
- watched-file and changed-file evidence;
- rendered PNG artifact evidence when rendering succeeds;
- child-sheet inclusion as the default watch behavior;
- artifact-first safety guidance for companion-plugin and agent flows;
- the distinction between a GUI reload request and a confirmed GUI document reload.

Evolving metadata:

- richer manifest files;
- additional visual-evidence artifact indexes;
- more detailed debounce timing fields;
- GUI-facing confirmation and session-consent metadata;
- upstream KiCad issue links that explain reload limitations.

For schematic GUI refresh, `reload_attempted=true` means the MCP server made a best-effort GUI-facing request. It does not imply that the already-open KiCad schematic document was confirmed to reload from disk. Clients must prefer `render_artifacts`, `manifest_path`, and structured visual evidence as authoritative review data.

Clients should ignore unknown fields in live-preview responses and should not
parse human-readable messages when a structured field is available.
