tweaking bits after docs meeting (#2896)

Author: thisisjofrank

examples/_data.ts

@@ -348,18 +348,13 @@ export const sidebar = [
         href: "/examples/sandbox_error_handling/",
         type: "example",
       },
-      {
-        title: "Error handling with custom error classes",
-        href: "/examples/sandbox_custom_error_classes/",
-        type: "example",
-      },
       {
         title: "Command cancellation",
         href: "/examples/sandbox_command_cancellation/",
         type: "example",
       },
       {
-        title: "Access string and binary output",
+        title: "Streaming access string and binary output",
         href: "/examples/sandbox_access_output/",
         type: "example",
       },
@@ -389,12 +384,12 @@ export const sidebar = [
         type: "example",
       },
       {
-        title: "Add read-write block storage to your Sandbox",
+        title: "Add read-write volumes to your Sandbox",
         href: "/examples/volumes_tutorial/",
         type: "example",
       },
       {
-        title: "Boot instantly with read-only images",
+        title: "Boot instantly with snapshots",
         href: "/examples/snapshots_tutorial/",
         type: "example",
       },

examples/sandbox/access_output.md

@@ -1,6 +1,6 @@
 ---
-title: "Access string and binary output"
-description: "Learn how to access string and binary output from commands in a sandbox."
+title: "Streaming access string and binary output"
+description: "Learn how to stream string and binary output from commands in a sandbox."
 url: /examples/sandbox_access_output/
 layout: sandbox-example.tsx
 ---

examples/sandbox/custom_error_classes.md

@@ -35,3 +35,31 @@ full status object, so you can branch on `status.code` or `status.success`, log
 diagnostics, or retry specific commands without losing context. This pattern is
 essential for robust automation where commands might fail due to user input,
 transient network issues, or missing dependencies.
+
+## Custom error classes
+
+You can handle errors with custom error classes in a sandbox.
+
+Catching `SandboxCommandError` lets you differentiate sandbox command failures
+from other exceptions. When the error is the `SandboxCommandError` class, you
+can read structured fields such as `error.code` or format `error.message` to
+decide whether to retry, escalate, or map exit codes to your own domain-specific
+errors:
+
+```ts
+import { Sandbox, SandboxCommandError } from "@deno/sandbox";
+
+await using sandbox = await Sandbox.create();
+
+try {
+  await sandbox.sh`exit 42`;
+} catch (error) {
+  if (error instanceof SandboxCommandError) {
+    console.log("Exit code:", error.code); // → 42
+    console.log("Error message:", error.message);
+  }
+}
+```
+
+This makes it easier to build higher-level automation that reacts intelligently
+to known failure modes instead of treating every thrown error the same.

examples/sandbox/error_handling.md

@@ -13,14 +13,14 @@ workloads or reduce memory for lighter tasks.
 import { Sandbox } from "@deno/sandbox";
 
 // Create a sandbox with 1GB of memory
-await using sandbox = await Sandbox.create({ memoryMb: 1024 });
+await using sandbox = await Sandbox.create({ memory: 1024 });
 ```
 
 ```ts
 import { Sandbox } from "@deno/sandbox";
 
 // Create a sandbox with 4GB of memory for memory-intensive workloads
-await using sandbox = await Sandbox.create({ memoryMb: 4096 });
+await using sandbox = await Sandbox.create({ memory: 4096 });
 
 // Check available memory
 const memInfo = await sandbox.deno.eval<{ total: number }>(
@@ -29,7 +29,7 @@ const memInfo = await sandbox.deno.eval<{ total: number }>(
 console.log("Total memory:", memInfo.total);
 ```
 
-Configuring memoryMb when creating the sandbox lets you tune resource usage per
+Configuring memory when creating the sandbox lets you tune resource usage per
 workload. Lightweight tasks can run in smaller sandboxes to conserve resources,
 while data-heavy scripts or compilations can request up to 4 GB to avoid
 out-of-memory failures.

examples/sandbox/memory.md

@@ -14,8 +14,7 @@ import { Sandbox } from "@deno/sandbox";
 
 await using sandbox = await Sandbox.create();
 
-const text = await sandbox.sh`pwd`.text();
-console.log("result:", text); // → "/home/sandbox\n"
+const cwd = await sandbox.sh`pwd`;
 ```
 
 For long‑running processes or large output, stream the stdout/stderr instead of

examples/sandbox/spawn_subprocess.md

@@ -6,16 +6,21 @@ layout: sandbox-example.tsx
 ---
 
 SSH access allows you to connect to a sandboxed environment securely over the
-SSH protocol. The `sandbox.exposeSsh()` method can be used to provide SSH access
-to a sandbox.
+SSH protocol. The `sandbox.create({ ssh: true })` method can be used to provide
+SSH access to a sandbox.
 
 ```ts
 import { Sandbox } from "@deno/sandbox";
 
-await using sandbox = await Sandbox.create();
+await using sandbox = await Sandbox.create({ ssh: true });
 
-// Get SSH credentials
-const { hostname, username } = await sandbox.exposeSsh();
+// Wait for Deploy to provision SSH access information.
+const creds = sandbox.ssh ?? await sandbox.exposeSsh();
+if (!creds) {
+  throw new Error("SSH credentials were not provisioned for this sandbox");
+}
+
+const { hostname, username } = creds;
 console.log(`ssh ${username}@${hostname}`);
 
 // Keep the process alive by sleeping, otherwise the sandbox will be destroyed

examples/sandbox/ssh_access.md

@@ -13,12 +13,14 @@ your script finishes or keep running for a set duration:
 import { Sandbox } from "@deno/sandbox";
 
 // Default: "session" - sandbox shuts down when you close/dispose the client
-await using sandbox = await Sandbox.create({ timeout: "session" });
+await using sandbox = await Sandbox.create({ timeout: "10m" });
 ```
 
 Supported duration suffixes: `s` (seconds), `m` (minutes).
 
-Examples: `"30s"`, `"5m"`, `"90s"` .
+Examples: `"30s"`, `"5m"`, `"90s"`. The default is `"session"`, which means the
+sandbox will automatically shut down when the client connection is closed or
+disposed.
 
 ```ts
 import { Sandbox } from "@deno/sandbox";