docs(cli): document the deploy plan, the construct diff and the write-back [RED-943]

[sorccu]

Rolls the stacked deploy-plan documentation (#510, #514, #516, #517, #519, #520, #521, #532, #540) into one PR on top of current main, as a single commit. Those PRs are closed in favour of this one. The content is theirs, rebased once onto the --schedule-on-deploy-threshold and --schedule-on-deploy-min-frequency additions that landed on main in the meantime.

What it documents

On cli/checkly-deploy.mdx and the Claude Code monitoring guide:

• The plan, on by default (RED-1016, flipped by RED-1100 for the next major version): what a planned deploy does, the plan token, --plan-token, --prune-relations, --dry-run and the confirmation_required envelope (RED-943), and what --no-plan does instead.
• The plan as the CLI prints it (RED-981): the overview table, the construct diff under each updated resource with its legend and the notes it can carry, masked secrets, totals in both tenses, a plan with nothing to apply, and the first plan of a project with its baseline note (RED-1055).
• The confirmation shows the plan (RED-984) and, in a terminal, offers to write changes made in Checkly into the code: literal values (RED-985), helper-spelled properties (RED-986), runtimeId and every monitor request (RED-991), sslCheckDomain, aiAutoRepairEnabled and prompt (RED-992), and every other resource type (RED-997), with what is refused and why, and the report printed afterwards.

Accuracy review

A second commit corrects what a review of the page against the CLI found: the legend under every construct diff sample (past tense after a deploy), the exported variable at the top of the --output sample, the pruned relation row naming its check or group, the select prompt layout, the changed: note joining every cause, the full maintenance window write-back list, the doubleCheck note, and the --dry-run, --verbose and --prune-relations fields saying what needs --plan.

Plan by default (RED-1100)

A third commit describes the plan as the default of checkly deploy and --no-plan as the opt-out, as checkly-cli #1513 makes it for the release candidate of the next major version: the samples run checkly deploy without --plan, the baseline note and the plan footer read as the CLI prints them, --plan-token and --prune-relations are "not available with --no-plan", and the first plan of a project also covers a project upgraded from an earlier major version. The Claude Code guide's preview sample becomes a planned preview, and the Playwright guide's deploy log shows the plan and the prompt.

Not in this PR: two deploy samples that were already out of date before it, the deploy --preview in the availability guide (old Create: layout) and the Do you want to continue? prompt in the Playwright Check Suite quickstart; both need the overview layout and the Apply these changes? prompt.

When to merge

After the major release of the checkly CLI that plans by default is published as latest. The release candidate goes out under the next dist-tag, so until the stable release npm install checkly still resolves to a CLI whose deploy has no plan at all.

🤖 Generated with Claude Code

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated
checkly-422f444a	🟢 Ready	View Preview	Oct 9, 2026, 6:06 AM