BP docs: process and terminal corrections

sites/browserpod/src/content/docs/13-reference/00-BrowserPod/01-createCustomTerminal.md

@@ -8,7 +8,7 @@ class BrowserPod {
 	createCustomTerminal(opts: {
 		cols?: number;
 		rows?: number;
-		onOutput: (buffer: ArrayBuffer, vt?: unknown) => void;
+		onOutput: (buffer: Uint8Array, vt?: number) => void;
 	}): Promise<Terminal>;
 }
 ```
@@ -21,7 +21,7 @@ class BrowserPod {
 
 - **cols (`number`, _optional_)** - The number of columns (width) for the terminal display. If not specified, a default width will be used.
 - **rows (`number`, _optional_)** - The number of rows (height) for the terminal display. If not specified, a default height will be used.
-- **onOutput (`function(buffer: ArrayBuffer, vt?: unknown) => void`)** - Callback function invoked whenever the terminal produces output. The buffer contains the raw terminal data, and vt contains optional VT escape sequence information.
+- **onOutput (`function(buffer: Uint8Array, vt?: number) => void`)** - Callback function invoked whenever the terminal produces output. The buffer contains the raw terminal data, and vt is the ID of the terminal that produced it.
 
 ## Returns
 

sites/browserpod/src/content/docs/13-reference/00-BrowserPod/08-run.md

@@ -1,6 +1,6 @@
 ---
 title: run
-description: "Run an executable inside a BrowserPod Pod, attach it to a terminal for input and output, and get back a Process handle for its result."
+description: "Run an executable inside a BrowserPod Pod, attach it to a terminal for input and output, and wait for its exit code."
 ---
 
 ```ts
@@ -14,7 +14,7 @@ class BrowserPod {
 			cwd?: string;
 			echo?: boolean;
 		}
-	): Promise<Process>;
+	): Process;
 }
 ```
 
@@ -33,8 +33,16 @@ class BrowserPod {
 
 ## Returns
 
-`run` returns a [Promise] which resolves to a [Process] object once the command finishes running.
+`run` returns a [Process], a thenable object. Awaiting it resolves to the exit code of the process once it exits, so you can check whether it succeeded or failed:
+
+```ts
+const exitCode = await pod.run("npm", ["install"], { terminal });
+if (exitCode !== 0) {
+	console.error(`npm install failed with exit code ${exitCode}`);
+}
+```
+
+If the process cannot be started or is killed by a signal, awaiting it throws an error instead.
 
-[Promise]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise
 [Terminal]: /docs/reference/Terminal
 [Process]: /docs/reference/Process

sites/browserpod/src/content/docs/13-reference/00-BrowserPod/index.md

@@ -41,10 +41,10 @@ const pod = await BrowserPod.boot({ apiKey: "...", storageKey: "my-project" });
 
 ### Run programs
 
-Use [`run`](/docs/reference/BrowserPod/run) to execute a program and get back a [Process](/docs/reference/Process):
+Use [`run`](/docs/reference/BrowserPod/run) to execute a program. It returns a [Process](/docs/reference/Process) that resolves to the exit code when awaited:
 
 ```ts
-const process = await pod.run("node", ["script.js"], { terminal });
+const exitCode = await pod.run("node", ["script.js"], { terminal });
 ```
 
 ### Manage the filesystem

sites/browserpod/src/content/docs/13-reference/03-Terminal/index.md

@@ -3,10 +3,12 @@ title: Terminal
 description: A handle to a terminal emulator running inside a Pod
 ---
 
-A `Terminal` is an opaque handle to a terminal emulator running inside a [Pod](/docs/reference/BrowserPod). It is created by [`createDefaultTerminal`](/docs/reference/BrowserPod/createDefaultTerminal) or [`createCustomTerminal`](/docs/reference/BrowserPod/createCustomTerminal), and passed to [`run`](/docs/reference/BrowserPod/run) to connect a process to I/O.
+A `Terminal` is a handle to a terminal emulator running inside a [Pod](/docs/reference/BrowserPod). It is created by [`createDefaultTerminal`](/docs/reference/BrowserPod/createDefaultTerminal) or [`createCustomTerminal`](/docs/reference/BrowserPod/createCustomTerminal), and passed to [`run`](/docs/reference/BrowserPod/run) to connect a process to I/O.
 
 ```ts
-class Terminal {}
+class Terminal {
+	write(data: string | Uint8Array): void;
+}
 ```
 
 ## Creating a Terminal
@@ -20,3 +22,12 @@ class Terminal {}
 const terminal = await pod.createDefaultTerminal(element);
 await pod.run("node", ["script.js"], { terminal });
 ```
+
+## Writing to a terminal
+
+`write` sends text or bytes directly to the terminal's output, without going through a process in the Pod. Running processes do not receive it as input. Use it to show your own messages alongside program output, such as the command about to run:
+
+```ts
+terminal.write("$ npm install\r\n");
+await pod.run("npm", ["install"], { terminal });
+```

sites/browserpod/src/content/docs/13-reference/04-Process/index.md

@@ -1,9 +1,11 @@
 ---
 title: Process
-description: A handle to a process that ran inside a Pod
+description: A handle to a process running inside a Pod
 ---
 
-A `Process` is an opaque handle to a program that ran inside a [Pod](/docs/reference/BrowserPod). It is returned by [`run`](/docs/reference/BrowserPod/run) once the process has exited.
+A `Process` is a handle to a process running inside a [Pod](/docs/reference/BrowserPod). It is returned by [`run`](/docs/reference/BrowserPod/run).
+
+`Process` is a thenable object: awaiting it resolves to the exit code of the process once it exits. If the process cannot be started or is killed by a signal, awaiting it throws an error instead.
 
 ```ts
 class Process {}
@@ -12,9 +14,5 @@ class Process {}
 ## Creating a Process
 
 ```ts
-const process = await pod.run("node", ["script.js"], { terminal });
+const exitCode = await pod.run("node", ["script.js"], { terminal });
 ```
-
-The [Promise] resolves to a `Process` when the program exits.
-
-[Promise]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise