# 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 |