@getmagical/cli 0.4.0 → 0.6.0

package/README.md

@@ -114,18 +114,26 @@ MCP server. MCP callers must provide `idempotencyKey` and
 current branch. Omit it to target main; branch-aware responses include
 `branchId: null` and the selected main `headVersionId`.
 
-This release adds exactly five commands: branch list, create, get, and merge,
-plus workbench patch readiness.
+Branch commands: list, create, get, merge-preview, discard-changes, and
+merge, plus
+workbench patch readiness.
 
 ```bash
 mgcl automations branches list --automation-id <automation-id> --json
 mgcl automations branches create --automation-id <automation-id> --name experiment --json
 mgcl --branch-id <branch-id> automations branches get --automation-id <automation-id> --json
 mgcl --branch-id <branch-id> automations update --id <automation-id> --input-json '{"baseVersionId":"<head-version-id>","name":"Experiment"}' --json
+mgcl --branch-id <branch-id> automations branches merge-preview --automation-id <automation-id> --json
+mgcl --branch-id <branch-id> automations branches discard-changes --automation-id <automation-id> --change-ids agent:update:<agent-id>:instructions --source-version-id <source-version-id> --target-version-id <target-version-id> --json
 mgcl --branch-id <branch-id> automations branches merge --automation-id <automation-id> --json
 mgcl --branch-id <branch-id> workbench patch readiness --target-draft-automation-id <automation-id> --operations-json '[{"setAutomationName":{"name":"Experiment readiness preview"}}]' --json
 ```
 
+Merge previews report agent edits per field, and settings per config key:
+`agent:update:<agent-id>:config.model`, `config.tools`, `config.plugins.memory`,
+or `config.devOnly` for the developer-only keys, with the key in `configKey`.
+Automation settings follow the same shape (`automation:config.systemPrompt`).
+
 Branch creation defaults to main. Use `--source-branch-id` and optionally
 `--source-version-id` to fork from another branch or an older version in that
 branch's history. Names must use lowercase letters or numbers separated by
@@ -135,7 +143,24 @@ leading or trailing dashes, repeated dashes, and over-length names are
 rejected before an API request. Branch IDs, not names, identify targets, and
 every automation or branch ID must be a UUID; malformed IDs are rejected
 before an API request.
-Merge previews the same change set as the web UI. A conflict returns
+`merge-preview` explains the merge without writing anything. Each change carries a
+stable `id`, a `kind`, and for agent edits the `agentId` and `field`
+(`name`, `description`, `instructions`, `inputSchema`, `outputSchema`,
+`config`, `agentLibraryEntity`, `type`), so a field main also changed
+conflicts on its own while the agent's other fields stay mergeable.
+Connections are keyed by `fromAgentId`/`toAgentId`, agent positions are one
+grouped `layout:agents` change that never conflicts, and a connection to an
+agent main deleted is a conflict. `conflictDescription` says why a change
+conflicts; `discardable` marks changes that can be reverted.
+
+`discard-changes` is the only conflict resolution: it reverts the named changes on
+the branch as a new branch version so main keeps its values, and returns the
+new head plus the refreshed preview. Pass `--source-version-id` and
+`--target-version-id` from the preview you acted on; the command is rejected
+when either head moved since. Discarding an added or removed agent also
+reverts its added or removed connections.
+
+`merge` previews the same change set as the web UI. A conflict returns
 `status: "conflict"`, does not change main or delete the branch, and exits
 nonzero so scripts gating on the exit code never mistake it for an applied
 merge. A conflict-free merge returns `status: "merged"`, the saved-main
@@ -145,7 +170,8 @@ are intentionally deferred.
 The global branch target is accepted by `automations update`, `automations
 run-draft`, `automations diff-from-published`, `workbench diagnostics`,
 `workbench schema-suggestions`, and `workbench patch preview`, `readiness`,
-and `apply`. It is required by `automations branches get` and `merge`. Other
+and `apply`. It is required by `automations branches get`, `merge-preview`,
+`discard-changes`, and `merge`. Other
 commands reject `--branch-id` before making an API request, and
 `mgcl --help` lists the branch-aware commands. Branch-aware responses identify the selected
 target with `branchId` and `headVersionId`. Merge returns `branchId`, its exact