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

CHANGELOG.md

@@ -14,6 +14,7 @@
 
 ### Changed
 
+- `base44 sandbox` help now explains that writes are committed but not checkpointed: a Restore or Revert in the builder rolls the app back to the last checkpoint and discards everything after it, so run `base44 sandbox checkpoint` after each unit of work and before stopping. The note appears on `sandbox`, `sandbox write`, `sandbox edit`, `sandbox run`, and `sandbox checkpoint`.
 - The `backend-and-client` template now scaffolds the same client convention editor-created apps use: `@base44/vite-plugin` + `src/lib/app-params.js`, with the SDK client on same-origin `/api` (`serverUrl: ''`). Under `base44 dev` the plugin proxies `/api` to the local dev backend, so scaffolded apps get local entities and functions; the app id is injected via `VITE_BASE44_APP_ID` by `base44 dev`, `base44 dev --remote`, and the build/deploy commands instead of being baked into source.
 
 ### Fixed

packages/cli/README.md

@@ -67,7 +67,7 @@ The CLI will guide you through project setup. For step-by-step tutorials, see th
 | [`sandbox edit`](https://docs.base44.com/developers/references/cli/commands/sandbox-edit) | Apply exact old→new string edits to a file in the sandbox |
 | [`sandbox grep`](https://docs.base44.com/developers/references/cli/commands/sandbox-grep) | Search files for a pattern in an app's remote sandbox |
 | [`sandbox run`](https://docs.base44.com/developers/references/cli/commands/sandbox-run) | Run a shell command in an app's remote sandbox |
-| [`sandbox checkpoint`](https://docs.base44.com/developers/references/cli/commands/sandbox-checkpoint) | Create a restore-point checkpoint of an app's remote sandbox |
+| [`sandbox checkpoint`](https://docs.base44.com/developers/references/cli/commands/sandbox-checkpoint) | Save a restore point in the builder's version history; run it after each unit of work, since sandbox writes are committed but not checkpointed and a Restore or Revert in the builder discards everything after the last checkpoint |
 | [`site deploy`](https://docs.base44.com/developers/references/cli/commands/site-deploy) | Deploy built site files to Base44 hosting |
 | [`site open`](https://docs.base44.com/developers/references/cli/commands/site-open) | Open the published site in your browser |
 | [`types generate`](https://docs.base44.com/developers/references/cli/commands/types-generate) | Generate TypeScript types from project resources |

packages/cli/src/cli/commands/sandbox/checkpoint.ts

@@ -27,14 +27,23 @@ async function checkpointAction(
 
 export function getSandboxCheckpointCommand(): Command {
   return new Base44Command("checkpoint", { supportsBranch: true })
-    .description("Create a restore-point checkpoint of an app's remote sandbox")
+    .description(
+      "Save a restore point in the builder's version history (run after each unit of work)",
+    )
     .option(
       "--name <name>",
-      "Optional message/title for the checkpoint (defaults to an auto-generated title)",
+      "Optional title, ideally a short summary of what changed (defaults to an auto-generated title)",
     )
     .addHelpText(
       "after",
       `
+Sandbox writes are committed but not checkpointed. Only checkpoints appear in
+the builder's version history, and a Restore or Revert there rolls the app back
+to the last checkpoint and discards everything written after it. Run this when
+you finish a unit of work and always before you stop, so the user can restore
+your work instead of losing it. Pending changes are flushed first, so the
+checkpoint captures your latest code.
+
 Examples:
   $ base44 sandbox checkpoint
   $ base44 sandbox checkpoint --name "before refactor"`,

packages/cli/src/cli/commands/sandbox/edit-file.ts

@@ -6,7 +6,7 @@ import { InvalidInputError } from "@/core/errors.js";
 import { getAppContext } from "@/core/project/index.js";
 import { editFile } from "@/core/resources/sandbox/api.js";
 import type { EditSpec } from "@/core/resources/sandbox/schema.js";
-import { resolveFlagOrStdin, toJsonStdout } from "./shared.js";
+import { CHECKPOINT_HELP, resolveFlagOrStdin, toJsonStdout } from "./shared.js";
 
 interface EditFileOptions {
   editsJson?: string;
@@ -80,6 +80,7 @@ export function getSandboxEditFileCommand(): Command {
       "after",
       `
 Each edit is { "old_text": "...", "new_text": "...", "replace_all"?: true }.
+${CHECKPOINT_HELP}
 
 Examples:
   $ echo '[{"old_text":"foo","new_text":"bar"}]' | base44 sandbox edit src/x.ts

packages/cli/src/cli/commands/sandbox/index.ts

@@ -5,11 +5,13 @@ import { getSandboxGrepCommand } from "./grep.js";
 import { getSandboxListDirectoryCommand } from "./list-directory.js";
 import { getSandboxReadFileCommand } from "./read-file.js";
 import { getSandboxRunCommandCommand } from "./run-command.js";
+import { CHECKPOINT_HELP } from "./shared.js";
 import { getSandboxWriteFileCommand } from "./write-file.js";
 
 export function getSandboxCommand(): Command {
   return new Command("sandbox")
     .description("Develop an app remotely via its server-side sandbox")
+    .addHelpText("after", CHECKPOINT_HELP)
     .addCommand(getSandboxListDirectoryCommand())
     .addCommand(getSandboxReadFileCommand())
     .addCommand(getSandboxWriteFileCommand())

packages/cli/src/cli/commands/sandbox/run-command.ts

@@ -3,7 +3,7 @@ import type { CLIContext, RunCommandResult } from "@/cli/types.js";
 import { Base44Command } from "@/cli/utils/index.js";
 import { getAppContext } from "@/core/project/index.js";
 import { runCommand } from "@/core/resources/sandbox/api.js";
-import { parsePositiveInt, toJsonStdout } from "./shared.js";
+import { CHECKPOINT_HELP, parsePositiveInt, toJsonStdout } from "./shared.js";
 
 interface RunCommandOptions {
   cwd?: string;
@@ -45,6 +45,8 @@ export function getSandboxRunCommandCommand(): Command {
     .addHelpText(
       "after",
       `
+A command that changes files needs a checkpoint too.${CHECKPOINT_HELP}
+
 Examples:
   $ base44 sandbox run "npm test"
   $ base44 sandbox run ls -la --cwd src`,

packages/cli/src/cli/commands/sandbox/shared.ts

@@ -5,6 +5,12 @@ import { InvalidInputError } from "@/core/errors.js";
 // one implementation of the `--json` serializer.
 export { toJsonStdout } from "@/cli/utils/index.js";
 
+export const CHECKPOINT_HELP = `
+Writes are committed but not checkpointed. Only checkpoints appear in the
+builder's version history, and a Restore or Revert there rolls the app back to
+the last checkpoint and discards everything written after it. Run
+\`base44 sandbox checkpoint\` when you finish a unit of work and before you stop.`;
+
 /**
  * Resolve a payload that may come from a flag or piped stdin.
  * Returns the flag value when set, otherwise reads stdin (without trimming, so

packages/cli/src/cli/commands/sandbox/write-file.ts

@@ -3,7 +3,7 @@ import type { CLIContext, RunCommandResult } from "@/cli/types.js";
 import { Base44Command } from "@/cli/utils/index.js";
 import { getAppContext } from "@/core/project/index.js";
 import { writeFile } from "@/core/resources/sandbox/api.js";
-import { resolveFlagOrStdin, toJsonStdout } from "./shared.js";
+import { CHECKPOINT_HELP, resolveFlagOrStdin, toJsonStdout } from "./shared.js";
 
 interface WriteFileOptions {
   content?: string;
@@ -38,7 +38,8 @@ export function getSandboxWriteFileCommand(): Command {
     .option("--overwrite", "Overwrite the file if it already exists")
     .addHelpText(
       "after",
-      `
+      `${CHECKPOINT_HELP}
+
 Examples:
   $ echo "hello" | base44 sandbox write notes.txt
   $ base44 sandbox write notes.txt --content "hello" --overwrite`,