Compatibility from 1.0.0
fbrcm 1.0.0 establishes a stable application interface and a released CLI JSON contract 1.0.0. The release, JSON contract, negotiated MCP protocol, and file formats have separate versions. Existing integer file-format versions stay at 1; the pre-1.0 in-place breaking-change exception has ended.
| Surface | Stability promise |
|---|---|
| Documented CLI syntax and behavior | Compatible throughout fbrcm 1.x: commands, arguments, flags, defaults, selection, effects, confirmations, environment variables, and exit meanings |
| JSON envelopes and schemas | Versioned compatibility for DTOs, codes, details, capability metadata, semantic rules, and artifacts |
| MCP tools | Stable public names, operation mappings, launch policy, discovered contracts, results, and authorization behavior for the same server configuration |
| Durable data | 1.0.0 configuration, identities, preferences, custom key configurations, themes, hook trust, drafts, retained snapshots, and plans remain readable on 1.x upgrades, directly or through a documented migration |
Breaking a supported interface requires an application major release. Incompatible JSON changes also require a contract major version. Compatible additions use minor versions; fingerprinted clarifications with no validation or semantic change may use a contract patch version. Closed enums are not implicitly extensible.
Use the installed binary's advertised schema and contract_version with its schemas. Published schema IDs are immutable. There is no CLI output-version negotiation flag; pin a binary release if you require an exact contract version. MCP protocol negotiation is separate from the shared JSON envelope version.
What is not a stable integration interface
- Human tables: columns, widths, labels, borders, colors, logs, progress, help wording, and prompts may change. Use JSON or MCP for automation.
- Default TUI bindings and layouts: shortcuts, panels, and mouse flows may evolve. Supported custom key-configuration syntax and saved action identifiers remain durable configuration and require compatibility or a documented migration.
- Exported Go packages: fbrcm is an application, not a supported Go library. Exported symbols may change in any release.
Transient rebuildable caches may be invalidated. Drafts and retained version snapshots are protected durable data even under a cache root. The promise covers upgrades from 1.0.0, not arbitrary pre-1.0 data, future files, or downgrades. Explicit user deletion and credential replacement keep their documented effects.
The released CLI lock rejects a changed generated fingerprint at the same contract version, and the release workflow refuses an unreleased lock. That fingerprint does not replace MCP or persisted-format compatibility review. See the full compatibility policy for versioning, migration, and release requirements.