fold/docs/compatibility.md

CLI and MCP compatibility

This checkpoint records the compatibility decision after the CLI/MCP surface convergence work. Aliases are not removed solely because they are old.

2026-07-29 checkpoint

Decision: retain every compatibility alias. They remain callable but hidden from normal CLI help or MCP tools/list/advertised schemas. Calls emit a single warning or structured deprecation metadata.

Removal is not yet eligible:

• first-party tests still exercise --input-type binary compatibility;
• Rust/Swift goldens and frontend tests were migrated from --format json to --format sarif, but an explicit compatibility test still covers the old spelling;
• repository documentation still contains migration examples and historical research commands using old forms;
• no deprecation telemetry or release feedback channel has produced evidence that external callers have migrated;
• Fold has not crossed the selected major-version boundary.

The earliest eligible removal boundary is Fold 1.0.0. Reaching that version is necessary but not sufficient: a later checkpoint must also show no first-party operational use, review available release feedback/telemetry, and retain migration documentation.

CLI migrations

Deprecated form	Canonical replacement	Current behavior
fold scan --input-type source ...	fold scan --mode source ...	Hidden, callable
fold scan --input-type binary --binary app	fold scan --mode binary --binary app	Hidden, callable
fold scan --format json -o report.json	fold scan --format sarif -o report.sarif	Callable; warns once
fold scan --profile freestanding ...	fold scan --preset freestanding ...	Callable; warns once
--null-deref-nullable-allocations	--nullable-allocations	Hidden, callable
fold fuzz-prep ...	fold fuzz prep ...	Hidden, callable; warns once
fold fuzz-run ...	fold fuzz run ...	Hidden, callable; warns once

Bare fold scan --profile remains canonical for performance metrics. Native finding JSON is --format findings-json; the deprecated json spelling means SARIF and must not be used when native JSON is intended.

MCP migrations

Advertised schemas contain canonical argument names only. The call boundary continues to accept these hidden aliases and returns a deprecations array with alias, replacement, and removal-boundary fields:

Deprecated argument	Canonical argument
binary_path	binary
max_functions	binary_max_functions
null_deref_nullable_allocations	nullable_allocations
fold.scan with background: true	fold.scan_start

Providing a canonical argument and its alias together is rejected as ambiguous.

Hidden tool aliases remain callable and return structured deprecation metadata:

Deprecated tool	Canonical tool
fold.get_job_findings	fold.scan_job_findings
fold.activate_scan_job	fold.scan_activate
fold.scan_project	fold.scan
fold.scan_rust	fold.scan with mode: "rust"
fold.scan_swift	fold.scan with mode: "swift"
fold.scan_binary	fold.scan with mode: "binary"
fold.find_duplicates	fold.scan with clone/equivalence detectors
fold.find_dead_code	fold.scan with dead-code detectors
fold.find_duplicate_classes	fold.scan with class-dup detectors
fold.find_security_issues	fold.scan with source security detectors
fold.find_binary_security_issues	fold.scan with binary security detectors