docs(sandbox): explain in --help why every unit of work needs a checkpoint

[carmelc]

Note

Description

Sandbox writes are committed to the app but do not create an entry in the builder's version history — so a Restore or Revert in the builder rolls the app back to the last checkpoint and silently discards everything written after it. This PR makes that contract explicit in --help output, so agents and users driving base44 sandbox know to run base44 sandbox checkpoint after each unit of work and before stopping. Documentation only: no runtime behavior changes.

Related Issue

None

Type of Change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Documentation update
• Refactoring (no functional changes)
• Other (please describe):

Changes Made

• Added a shared CHECKPOINT_HELP constant in packages/cli/src/cli/commands/sandbox/shared.ts so the warning is written once and reused.
• Appended the note to --help for the sandbox parent command and for sandbox write, sandbox edit, and sandbox run (the run text adds "A command that changes files needs a checkpoint too.").
• Rewrote sandbox checkpoint's help: the description is now "Save a restore point in the builder's version history (run after each unit of work)", with a longer addHelpText block explaining why, plus a note that pending changes are flushed first so the checkpoint captures the latest code.
• Reworded --name from "Optional message/title for the checkpoint" to steer toward a short summary of what changed.
• Updated the sandbox checkpoint row in packages/cli/README.md and added a CHANGELOG.md entry under Changed.

Testing

• I have tested these changes locally
• I have added/updated tests as needed
• All tests pass (npm test)

Checklist

• My code follows the project's style guidelines
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation (if applicable)
• My changes generate no new warnings
• I have updated docs/ (AGENTS.md) if I made architectural changes

Additional Notes

No tests were added or changed — the diff only touches help strings, and the existing packages/cli/tests/cli/sandbox.spec.ts asserts on command behavior rather than help text, so nothing there needed updating. Typecheck and lint were not run in this environment (those commands required approval); both are expected to be unaffected since the only source change is one new exported string constant and its call sites. The docs/ checkbox is unchecked because this is a help-text change, not an architectural one.

---

_{🤖 Generated by Claude | 2026-09-22 06:57 UTC | 1a53729}

[github-actions]

🚀 Package Preview Available!

---

Install this PR's preview build with npm:

npm i @base44-preview/cli@0.1.15-pr.632.1a53729

Prefer not to change any import paths? Install using npm alias so your code still imports base44:

npm i "base44@npm:@base44-preview/cli@0.1.15-pr.632.1a53729"

Or add it to your package.json dependencies:

{
  "dependencies": {
    "base44": "npm:@base44-preview/cli@0.1.15-pr.632.1a53729"
  }
}

• 📦 Preview Package: @base44-preview/cli@0.1.15-pr.632.1a53729
• 🔗 View this commit on GitHub

---

_{Preview published to npm registry — try new features instantly!}