diff --git a/clients/python/src/sqlfs/sandbox.py b/clients/python/src/sqlfs/sandbox.py
index cb4acef..0bea987 100644
--- a/clients/python/src/sqlfs/sandbox.py
+++ b/clients/python/src/sqlfs/sandbox.py
@@ -49,12 +49,57 @@
 #: client via ``Client(max_file_size=...)`` or disable with ``max_file_size=0``.
 DEFAULT_MAX_FILE_SIZE = 64 * 1024 * 1024
 
+#: Largest file the ``python3`` runtime (CPython compiled to WASM) can read via
+#: ``open()``. CPython reads sandbox files through an 8 MiB SharedArrayBuffer
+#: IPC bridge; ``open()`` on a larger file fails with an opaque
+#: ``FileNotFoundError`` / ``OSError``. The bytes still ingest fine and stay
+#: readable from bash (``cat``/``grep``/``awk``) and ``js-exec`` — only
+#: ``python3`` cannot read them.
+CPYTHON_READ_LIMIT = 8 * 1024 * 1024
+
 
 def _content_size(content: Union[str, bytes]) -> int:
     """Raw byte length of a write payload (``str`` measured as UTF-8)."""
     return len(content.encode("utf-8")) if isinstance(content, str) else len(content)
 
 
+def _enforce_cpython_read_limit(
+    files: Mapping[str, Union[str, bytes]],
+    *,
+    allow_oversized: bool,
+) -> None:
+    """Reject files the ``python3`` runtime could not later ``open()``.
+
+    Raises ``ValidationError`` (code ``EFILE_TOO_LARGE_FOR_CPYTHON``) naming
+    every file above :data:`CPYTHON_READ_LIMIT`. Pass ``allow_oversized=True``
+    to ingest anyway — the file is stored and usable from bash/js-exec, but
+    ``python3`` ``open()`` will fail on it.
+    """
+    if allow_oversized:
+        return
+    too_big = [
+        (path, size)
+        for path, content in files.items()
+        if (size := _content_size(content)) > CPYTHON_READ_LIMIT
+    ]
+    if too_big:
+        details = [
+            f"{path} ({size} bytes > {CPYTHON_READ_LIMIT} python3 open() limit)"
+            for path, size in too_big
+        ]
+        raise ValidationError(
+            "file exceeds the 8 MiB limit that the python3 (CPython WASM) runtime "
+            "can read via open(): "
+            + "; ".join(details)
+            + ". The bytes ingest fine and stay usable from bash (cat/grep/awk) and "
+            "js-exec — only python3 open() will fail on these files. Pass "
+            "allow_oversized=True to ingest anyway, or split the file into <8 MiB "
+            "chunks if you need to read it from python3.",
+            code="EFILE_TOO_LARGE_FOR_CPYTHON",
+            details=details,
+        )
+
+
 def _enforce_max_file_size(
     files: Mapping[str, Union[str, bytes]],
     max_file_size: int,
@@ -409,17 +454,25 @@ def ingest_files(
         files: Mapping[str, Union[str, bytes]],
         *,
         base_path: str = "/home/user/project",
+        allow_oversized: bool = False,
     ) -> Dict[str, Any]:
         """`POST /ingest-files` — write a JSON manifest of files (auto base64).
 
         Keys are paths relative to `base_path`. Values may be `str` (encoded
         utf-8) or `bytes` (encoded as-is); the SDK base64-encodes them.
 
-        Each file is checked against the client's ``max_file_size`` first; an
-        oversized file raises ``ValidationError`` (code ``EFILE_TOO_LARGE``)
-        before anything is encoded or sent over the network.
+        Two client-side checks run before anything is encoded or sent:
+
+        1. Each file is checked against the client's ``max_file_size``; an
+           oversized file raises ``ValidationError`` (code ``EFILE_TOO_LARGE``).
+        2. Any file larger than 8 MiB (:data:`CPYTHON_READ_LIMIT`) raises
+           ``ValidationError`` (code ``EFILE_TOO_LARGE_FOR_CPYTHON``) because the
+           ``python3`` runtime cannot ``open()`` it. Pass ``allow_oversized=True``
+           to ingest anyway — the file stays usable from bash/js-exec, but
+           ``python3`` ``open()`` will fail on it.
         """
         _enforce_max_file_size(files, self._max_file_size)
+        _enforce_cpython_read_limit(files, allow_oversized=allow_oversized)
         encoded: Dict[str, str] = {}
         for path, content in files.items():
             data = content.encode("utf-8") if isinstance(content, str) else content
diff --git a/clients/python/tests/test_client.py b/clients/python/tests/test_client.py
index cea6142..980e531 100644
--- a/clients/python/tests/test_client.py
+++ b/clients/python/tests/test_client.py
@@ -622,6 +622,35 @@ def test_ingest_files_base64_encodes():
     assert sent["files"]["b.bin"] == base64.b64encode(b"\x00\x01").decode()
 
 
+@respx.mock
+def test_ingest_files_blocks_oversized_for_cpython():
+    route = respx.post(f"{BASE_URL}/v1/sandboxes/sb/ingest-files").mock(
+        return_value=httpx.Response(200, json={"status": "ok", "fileCount": 1})
+    )
+    sb = make_client().sandboxes.attach("sb")
+    big = b"\x00" * (8 * 1024 * 1024 + 1)
+    with pytest.raises(ValidationError) as exc:
+        sb.ingest_files({"big.csv": big})
+    assert exc.value.code == "EFILE_TOO_LARGE_FOR_CPYTHON"
+    limit = 8 * 1024 * 1024
+    assert exc.value.details == [f"big.csv ({len(big)} bytes > {limit} python3 open() limit)"]
+    # Nothing sent over the network.
+    assert route.call_count == 0
+
+
+@respx.mock
+def test_ingest_files_allow_oversized_bypasses_cpython_check():
+    route = respx.post(f"{BASE_URL}/v1/sandboxes/sb/ingest-files").mock(
+        return_value=httpx.Response(200, json={"status": "ok", "fileCount": 1})
+    )
+    sb = make_client().sandboxes.attach("sb")
+    big = b"\x00" * (8 * 1024 * 1024 + 1)
+    sb.ingest_files({"big.csv": big}, allow_oversized=True)
+    assert route.call_count == 1
+    sent = json.loads(route.calls[0].request.content.decode())
+    assert list(sent["files"].keys()) == ["big.csv"]
+
+
 # ── Error mapping ────────────────────────────────────────────────────────────
 @respx.mock
 def test_400_maps_to_validation_error():
diff --git a/clients/typescript/src/sandbox.ts b/clients/typescript/src/sandbox.ts
index 2efd1f3..88f11f0 100644
--- a/clients/typescript/src/sandbox.ts
+++ b/clients/typescript/src/sandbox.ts
@@ -216,9 +216,11 @@ export class Sandbox {
 
 	async ingestFiles(
 		files: Record<string, FileContent>,
-		options: { basePath?: string } = {},
+		options: { basePath?: string; allowOversized?: boolean } = {},
 	): Promise<Record<string, unknown>> {
 		enforceMaxFileSize(files, this.maxFileSize);
+		// Files >8 MiB can't be read by python3's open() (CPython WASM IPC bridge cap).
+		enforceCpythonReadLimit(files, options.allowOversized ?? false);
 		const encoded: Record<string, string> = Object.create(null) as Record<string, string>;
 		for (const [path, content] of Object.entries(files)) {
 			encoded[path] = toBase64(content);
@@ -288,6 +290,39 @@ function enforceMaxFileSize(files: Record<string, FileContent>, maxFileSize: num
 	});
 }
 
+/**
+ * Largest file the `python3` runtime (CPython compiled to WASM) can read via
+ * `open()`. CPython reads sandbox files through an 8 MiB SharedArrayBuffer IPC
+ * bridge; `open()` on a larger file fails with an opaque error. The bytes still
+ * ingest fine and stay readable from bash and js-exec — only `python3` cannot
+ * read them.
+ */
+export const cpythonReadLimit = 8 * 1024 * 1024;
+
+/**
+ * Reject files the `python3` runtime could not later `open()`. Throws
+ * ValidationError (code `EFILE_TOO_LARGE_FOR_CPYTHON`) unless `allowOversized`
+ * is set — in which case the file ingests but `python3` open() fails on it.
+ */
+function enforceCpythonReadLimit(files: Record<string, FileContent>, allowOversized: boolean): void {
+	if (allowOversized) {
+		return;
+	}
+	const tooBig = Object.entries(files)
+		.map(([path, content]) => [path, contentSize(content)] as const)
+		.filter(([, size]) => size > cpythonReadLimit);
+	if (tooBig.length === 0) {
+		return;
+	}
+	const details = tooBig.map(([path, size]) => `${path} (${size} bytes > ${cpythonReadLimit} python3 open() limit)`);
+	throw new ValidationError(
+		`file exceeds the 8 MiB limit that the python3 (CPython WASM) runtime can read via open(): ${details.join(
+			"; ",
+		)}. The bytes ingest fine and stay usable from bash (cat/grep/awk) and js-exec — only python3 open() will fail on these files. Pass allowOversized: true to ingest anyway, or split the file into <8 MiB chunks if you need to read it from python3.`,
+		{ code: "EFILE_TOO_LARGE_FOR_CPYTHON", details },
+	);
+}
+
 function toBytes(content: FileContent): Uint8Array<ArrayBuffer> {
 	if (typeof content === "string") {
 		return new TextEncoder().encode(content);
diff --git a/clients/typescript/tests/files.test.ts b/clients/typescript/tests/files.test.ts
index 257aa2d..517718a 100644
--- a/clients/typescript/tests/files.test.ts
+++ b/clients/typescript/tests/files.test.ts
@@ -63,4 +63,28 @@ describe("TypeScript SQL-FS SDK files", () => {
 		);
 		expect(blocked.fetchMock).not.toHaveBeenCalled();
 	});
+
+	it("blocks ingest of files >8 MiB the python3 runtime can't open()", async () => {
+		const { fetchMock } = makeFetch([jsonResponse(200, {})]);
+		const sb = makeClient(fetchMock).sandboxes.attach("sb");
+		const big = new Uint8Array(8 * 1024 * 1024 + 1);
+
+		await expect(sb.ingestFiles({ "big.csv": big })).rejects.toMatchObject({
+			code: "EFILE_TOO_LARGE_FOR_CPYTHON",
+			details: [`big.csv (${big.byteLength} bytes > ${8 * 1024 * 1024} python3 open() limit)`],
+		});
+		// Nothing should have been sent over the network.
+		expect(fetchMock).not.toHaveBeenCalled();
+	});
+
+	it("ingests an oversized file when allowOversized is set", async () => {
+		const { fetchMock, captured } = makeFetch([jsonResponse(200, { count: 1 })]);
+		const sb = makeClient(fetchMock).sandboxes.attach("sb");
+		const big = new Uint8Array(8 * 1024 * 1024 + 1);
+
+		await expect(sb.ingestFiles({ "big.csv": big }, { allowOversized: true })).resolves.toEqual({ count: 1 });
+		expect(fetchMock).toHaveBeenCalledTimes(1);
+		const sentBody = captured[0]?.body as { files: Record<string, string> };
+		expect(Object.keys(sentBody.files)).toEqual(["big.csv"]);
+	});
 });
diff --git a/plugins/sql-fs/.claude-plugin/plugin.json b/plugins/sql-fs/.claude-plugin/plugin.json
index 5b302f3..c2cf5cd 100644
--- a/plugins/sql-fs/.claude-plugin/plugin.json
+++ b/plugins/sql-fs/.claude-plugin/plugin.json
@@ -1,6 +1,6 @@
 {
 	"name": "sql-fs",
-	"version": "1.1.0",
+	"version": "1.1.1",
 	"description": "Operator skill for the SQL-FS API — persistent bash sandbox service with SQL-backed filesystem",
 	"author": {
 		"name": "Harry Nguyen",
diff --git a/plugins/sql-fs/skills/api/SKILL.md b/plugins/sql-fs/skills/api/SKILL.md
index 5dd43f8..7cdcbf7 100644
--- a/plugins/sql-fs/skills/api/SKILL.md
+++ b/plugins/sql-fs/skills/api/SKILL.md
@@ -14,11 +14,11 @@ Invoke with optional sub-commands:
 
 | Invocation | What happens |
 |---|---|
-| `/sqlfs:api` | General assistant — answer questions, generate commands |
-| `/sqlfs:api setup` | Walk through auth bootstrap and first sandbox |
-| `/sqlfs:api exec <script>` | Generate a ready-to-run exec-sync curl for `$ARGUMENTS` |
-| `/sqlfs:api ingest <path>` | Generate an ingest-files payload for a local directory |
-| `/sqlfs:api explore` | Load the active sandbox tree and start exploring |
+| `/sql-fs:api` | General assistant — answer questions, generate commands |
+| `/sql-fs:api setup` | Walk through auth bootstrap and first sandbox |
+| `/sql-fs:api exec <script>` | Generate a ready-to-run exec-sync curl for `$ARGUMENTS` |
+| `/sql-fs:api ingest <path>` | Generate an ingest-files payload for a local directory |
+| `/sql-fs:api explore` | Load the active sandbox tree and start exploring |
 
 Current arguments: **$ARGUMENTS**
 
@@ -43,21 +43,21 @@ Exception: `POST /v1/auth/bootstrap` is unauthenticated — it is how you obtain
 
 ## Supporting docs — read these when relevant
 
-All reference material lives under `plugins/sqlfs/skills/api/` in this project:
+All reference material lives under `plugins/sql-fs/skills/api/` in this project:
 
-- **Setup & Auth** → `plugins/sqlfs/skills/api/SETUP.md`
+- **Setup & Auth** → `plugins/sql-fs/skills/api/SETUP.md`
   Read this when the user asks about tokens, first-time setup, or multi-tenant config.
 
-- **Endpoint reference** → `plugins/sqlfs/skills/api/ref/endpoints.md`
+- **Endpoint reference** → `plugins/sql-fs/skills/api/ref/endpoints.md`
   Full schema for every route. Read this when generating curl commands.
 
-- **Error codes** → `plugins/sqlfs/skills/api/ref/errors.md`
+- **Error codes** → `plugins/sql-fs/skills/api/ref/errors.md`
   HTTP → FS code mapping. Read this when debugging API responses.
 
-- **Bash capabilities** → `plugins/sqlfs/skills/api/ref/bash.md`
+- **Bash capabilities** → `plugins/sql-fs/skills/api/ref/bash.md`
   What just-bash supports and what it doesn't. Read this before writing scripts.
 
-- **Working examples** → `plugins/sqlfs/skills/api/examples/`
+- **Working examples** → `plugins/sql-fs/skills/api/examples/`
   - `quickstart.sh` — create sandbox, write file, exec, delete
   - `ingest-files.sh` — upload a local folder via the `ingest-files` JSON manifest
   - `ingest-explore.sh` — load a codebase and grep/cat via bash_exec
@@ -74,7 +74,7 @@ response shapes, and known gotchas from the live API.
 2. Sandbox filesystem survives session eviction (Postgres is durable). Shell state (env vars,
    cwd, functions) resets after 10 min of idle.
 3. Never produce `curl` commands that omit `-s` — noisy progress meters obscure the output.
-4. For any task that touches files: read `plugins/sqlfs/skills/api/ref/endpoints.md` first.
+4. For any task that touches files: read `plugins/sql-fs/skills/api/ref/endpoints.md` first.
 
 ---
 
diff --git a/plugins/sql-fs/skills/api/ref/endpoints.md b/plugins/sql-fs/skills/api/ref/endpoints.md
index d37fa29..3377469 100644
--- a/plugins/sql-fs/skills/api/ref/endpoints.md
+++ b/plugins/sql-fs/skills/api/ref/endpoints.md
@@ -340,7 +340,7 @@ curl -s -X POST "$BASE_URL/v1/sandboxes/$SB/exec-sync-batch" \
   -d '{
     "scripts": [
       {"id": "tree", "script": "find /home/user -type f | head -20"},
-      {"id": "uname", "script": "uname -srm"}
+      {"id": "count", "script": "find /home/user -type f | wc -l"}
     ],
     "timeoutMs": 30000,
     "readOnly": true
@@ -365,7 +365,7 @@ Response `200`:
 {
   "results": [
     {"id": "tree", "stdout": "...", "stderr": "", "exitCode": 0, "durationMs": 42},
-    {"id": "uname", "stdout": "Linux ...", "stderr": "", "exitCode": 0, "durationMs": 8}
+    {"id": "count", "stdout": "12\n", "stderr": "", "exitCode": 0, "durationMs": 8}
   ]
 }
 ```
diff --git a/plugins/sql-fs/skills/py-sdk/SETUP.md b/plugins/sql-fs/skills/py-sdk/SETUP.md
index 723481a..dff76f9 100644
--- a/plugins/sql-fs/skills/py-sdk/SETUP.md
+++ b/plugins/sql-fs/skills/py-sdk/SETUP.md
@@ -96,7 +96,7 @@ with Client(
 ) as fs:
     sb = fs.sandboxes.create(name="smoke-test")
     try:
-        result = sb.exec("echo hello && uname -srm")
+        result = sb.exec("echo hello && pwd")
         assert result.ok, f"unexpected exit {result.exit_code}: {result.error}"
         print(result.stdout)
     finally:
diff --git a/plugins/sql-fs/skills/py-sdk/SKILL.md b/plugins/sql-fs/skills/py-sdk/SKILL.md
index 19c8b0c..c4953fc 100644
--- a/plugins/sql-fs/skills/py-sdk/SKILL.md
+++ b/plugins/sql-fs/skills/py-sdk/SKILL.md
@@ -16,11 +16,11 @@ Invoke with optional sub-commands:
 
 | Invocation | What happens |
 |---|---|
-| `/sqlfs:py-sdk` | General assistant — answer questions, generate snippets |
-| `/sqlfs:py-sdk setup` | Walk through install, env vars, first sandbox |
-| `/sqlfs:py-sdk exec <script>` | Generate a ready-to-run `sb.exec(...)` snippet for `$ARGUMENTS` |
-| `/sqlfs:py-sdk ingest <path>` | Generate an `sb.ingest_files(...)` snippet for a local directory |
-| `/sqlfs:py-sdk explore` | Build an `exec_batch` exploration script for the active sandbox |
+| `/sql-fs:py-sdk` | General assistant — answer questions, generate snippets |
+| `/sql-fs:py-sdk setup` | Walk through install, env vars, first sandbox |
+| `/sql-fs:py-sdk exec <script>` | Generate a ready-to-run `sb.exec(...)` snippet for `$ARGUMENTS` |
+| `/sql-fs:py-sdk ingest <path>` | Generate an `sb.ingest_files(...)` snippet for a local directory |
+| `/sql-fs:py-sdk explore` | Build an `exec_batch` exploration script for the active sandbox |
 
 Current arguments: **$ARGUMENTS**
 
@@ -65,24 +65,24 @@ either `auth_secret=...` (with `sub=...`) or a pre-minted `token=...`.
 
 ## Supporting docs — read these when relevant
 
-All reference material lives under `plugins/sqlfs/skills/py-sdk/` in this project:
+All reference material lives under `plugins/sql-fs/skills/py-sdk/` in this project:
 
-- **Setup & auth** → `plugins/sqlfs/skills/py-sdk/SETUP.md`
+- **Setup & auth** → `plugins/sql-fs/skills/py-sdk/SETUP.md`
   Read this when the user asks about install, env vars, token vs auth_secret, or first-time setup.
 
-- **Client reference** → `plugins/sqlfs/skills/py-sdk/ref/client.md`
+- **Client reference** → `plugins/sql-fs/skills/py-sdk/ref/client.md`
   `Client(...)` constructor + `client.sandboxes.{list,create,get,attach,delete}`. Read this for sandbox lifecycle.
 
-- **Sandbox reference** → `plugins/sqlfs/skills/py-sdk/ref/sandbox.md`
+- **Sandbox reference** → `plugins/sql-fs/skills/py-sdk/ref/sandbox.md`
   `sb.exec / exec_batch / exec_stream`, `sb.ingest_files`, `sb.delete`. Read this for everything an agent does inside a sandbox.
 
-- **Models reference** → `plugins/sqlfs/skills/py-sdk/ref/models.md`
+- **Models reference** → `plugins/sql-fs/skills/py-sdk/ref/models.md`
   Field-by-field shape of `ExecResult`, `BatchExecResult`, `StreamEvent`, `SandboxRecord`, etc. Read this when shaping return-value handling.
 
-- **Error reference** → `plugins/sqlfs/skills/py-sdk/ref/errors.md`
+- **Error reference** → `plugins/sql-fs/skills/py-sdk/ref/errors.md`
   Exception hierarchy + HTTP-status mapping. Read this when writing `try/except` blocks.
 
-- **Working examples** → `plugins/sqlfs/skills/py-sdk/examples/`
+- **Working examples** → `plugins/sql-fs/skills/py-sdk/examples/`
   - `quickstart.py` — create sandbox, ingest, exec, delete
   - `ingest-explore.py` — load a codebase via `ingest_files` then explore via `exec_batch`
   - `exec-stream.py` — SSE streaming with proper iteration
@@ -103,7 +103,7 @@ method names, parameter spellings, and known gotchas from the SDK.
    the finally block — sandboxes survive process exit and accumulate.
 4. **Sandbox filesystem is durable** (Postgres-backed). Bash session state (env vars,
    cwd, shell functions) resets after 10 min idle — re-export anything you need.
-5. **For any task that runs scripts**: read `plugins/sqlfs/skills/py-sdk/ref/sandbox.md`
+5. **For any task that runs scripts**: read `plugins/sql-fs/skills/py-sdk/ref/sandbox.md`
    first to use the right method and timeout shape.
 
 ---
@@ -143,11 +143,15 @@ methods are banned for agent use.
 a local folder into a fresh sandbox (single HTTP round-trip, base64-safe for binary).
 After ingest, all further interaction must be via `sb.exec / exec_batch / exec_stream`.
 
-**Per-file size limit:** every write path (`ingest_files`, `fs.write`, `fs.write_files`)
-enforces `Client(max_file_size=...)` — default **64 MiB** — **before** anything is
-encoded or sent. An oversized file raises `ValidationError(code="EFILE_TOO_LARGE")`
+**Per-file size limits (client-side):** every write path (`ingest_files`, `fs.write`,
+`fs.write_files`) enforces `Client(max_file_size=...)` — default **64 MiB** — **before**
+anything is encoded or sent. An oversized file raises `ValidationError(code="EFILE_TOO_LARGE")`
 client-side (no network round-trip). Raise it via `Client(max_file_size=...)` or
-disable with `max_file_size=0`. See `ref/client.md`.
+disable with `max_file_size=0`. Additionally, `ingest_files` rejects any file **> 8 MiB**
+with `ValidationError(code="EFILE_TOO_LARGE_FOR_CPYTHON")` because the `python3` runtime
+(CPython WASM) can't `open()` it; pass `allow_oversized=True` to ingest anyway (the bytes
+stay usable from bash/`js-exec`, only `python3 open()` fails), or split into <8 MiB chunks.
+See `ref/client.md` and `ref/sandbox.md`.
 
 When a user asks for an `sb.fs.*` snippet, **decline politely and produce the exec
 equivalent instead**, citing this policy. If the workflow truly cannot be expressed
diff --git a/plugins/sql-fs/skills/py-sdk/examples/quickstart.py b/plugins/sql-fs/skills/py-sdk/examples/quickstart.py
index 7dabdaa..3eeac2e 100644
--- a/plugins/sql-fs/skills/py-sdk/examples/quickstart.py
+++ b/plugins/sql-fs/skills/py-sdk/examples/quickstart.py
@@ -30,7 +30,7 @@ def main() -> int:
         print(f"created sandbox {sb.id}")
         try:
             # Single buffered exec — get back a flat ExecResult.
-            r = sb.exec("echo hello && uname -srm")
+            r = sb.exec("echo hello && pwd")
             if not r.ok:
                 print(f"unexpected exit {r.exit_code}: {r.error}", file=sys.stderr)
                 return 1
diff --git a/plugins/sql-fs/skills/py-sdk/ref/client.md b/plugins/sql-fs/skills/py-sdk/ref/client.md
index abddcbf..b1df8bb 100644
--- a/plugins/sql-fs/skills/py-sdk/ref/client.md
+++ b/plugins/sql-fs/skills/py-sdk/ref/client.md
@@ -50,6 +50,11 @@ fs = Client(base_url=..., auth_secret=..., sub="agent", max_file_size=128 * 1024
 fs = Client(base_url=..., auth_secret=..., sub="agent", max_file_size=0)                   # disable
 ```
 
+> The `max_file_size` check is separate from the 8 MiB `python3` read limit that
+> `ingest_files` enforces — see `ref/sandbox.md`. A file between 8 MiB and
+> `max_file_size` ingests fine but can't be read by the `python3` runtime unless
+> you pass `allow_oversized=True`.
+
 > Sizing note: the server caps the whole HTTP request body (default 256 MB) and
 > base64 inflates content ~33%, so the practical per-request ceiling is ~190 MB
 > of raw bytes regardless of `max_file_size`. The default 64 MiB keeps a single
@@ -187,12 +192,13 @@ The `Client` retries up to `max_retries` times on **transient** failures only:
 | 5xx | **Yes** — exponential jitter, capped at 8 s per attempt |
 | network (DNS, TCP, TLS, read-timeout) | **Yes** — exponential jitter |
 
-After `max_retries` exhaustion the SDK raises `ServerError` (for 5xx) or
-`TransportError` (for network failures). Streaming endpoints
-(`exec_stream`) are **not** retried — they have at-most-once
-semantics because the server can't safely re-execute a script.
+`exec` / `exec_batch` are only retried on transient 5xx when `read_only=True`
+(always safe) or when you opt in with `retry_on_5xx=True`; otherwise the server
+can't safely re-run an arbitrary write. `exec_stream` is **never** retried —
+at-most-once semantics. After `max_retries` exhaustion the SDK raises
+`ServerError` (for 5xx) or `TransportError` (for network failures).
 
-See `plugins/sqlfs/skills/py-sdk/ref/errors.md` for the full exception
+See `plugins/sql-fs/skills/py-sdk/ref/errors.md` for the full exception
 hierarchy.
 
 ---
diff --git a/plugins/sql-fs/skills/py-sdk/ref/errors.md b/plugins/sql-fs/skills/py-sdk/ref/errors.md
index 6ac8bcb..eb6da26 100644
--- a/plugins/sql-fs/skills/py-sdk/ref/errors.md
+++ b/plugins/sql-fs/skills/py-sdk/ref/errors.md
@@ -26,7 +26,8 @@ SQLFSError                    base — never raised directly by the SDK
 ├── AuthError                     401 / 403
 ├── NotFoundError                 404
 ├── ConflictError                 409 (EEXIST, ENOTEMPTY)
-├── ValidationError               400 (INVALID_INPUT, EISDIR, ENOTDIR, EINVAL, ELOOP); also client-side EFILE_TOO_LARGE
+├── ValidationError               400 (INVALID_INPUT, EISDIR, ENOTDIR, EINVAL, ELOOP); 422 (EREADONLY_VIOLATION);
+│                                 also client-side EFILE_TOO_LARGE / EFILE_TOO_LARGE_FOR_CPYTHON
 ├── ExecTimeoutError              408 (script ran longer than timeout_ms)
 ├── RateLimitError                429
 ├── ServerError                   5xx after retries exhausted
@@ -62,7 +63,8 @@ oversized file fails **before** anything is base64-encoded or sent:
 
 | `code` | Raised by | Cause |
 |---|---|---|
-| `EFILE_TOO_LARGE` | `ingest_files`, `fs.write`, `fs.write_files` | A file exceeds the client's `max_file_size`. `e.status` is `None` (no HTTP round-trip happened); `e.details` lists each offending `path (size > limit)`. |
+| `EFILE_TOO_LARGE` | `ingest_files`, `fs.write`, `fs.write_files` | A file exceeds the client's `max_file_size` (default 64 MiB). `e.status` is `None` (no HTTP round-trip happened); `e.details` lists each offending `path (size > limit)`. |
+| `EFILE_TOO_LARGE_FOR_CPYTHON` | `ingest_files` | A file exceeds **8 MiB**, which the `python3` runtime (CPython WASM) can't `open()`. `e.status` is `None`; `e.details` lists each offending path. Pass `allow_oversized=True` to ingest anyway (usable from bash/`js-exec`, not `python3`), or split into <8 MiB chunks. |
 
 ```python
 from sqlfs import ValidationError
@@ -71,10 +73,14 @@ try:
     sb.ingest_files({"huge.bin": payload})
 except ValidationError as e:
     if e.code == "EFILE_TOO_LARGE":
-        print("too big, never sent:", e.details)   # e.status is None
+        print("too big, never sent:", e.details)            # e.status is None
+    elif e.code == "EFILE_TOO_LARGE_FOR_CPYTHON":
+        # >8 MiB: python3 can't open it. Ingest for bash/js-exec use anyway:
+        sb.ingest_files({"huge.bin": payload}, allow_oversized=True)
 ```
 
-Set `max_file_size=0` on the `Client` to disable this check.
+Set `max_file_size=0` on the `Client` to disable the `EFILE_TOO_LARGE` check. The
+8 MiB `EFILE_TOO_LARGE_FOR_CPYTHON` guard is bypassed per-call with `allow_oversized=True`.
 
 ---
 
diff --git a/plugins/sql-fs/skills/py-sdk/ref/sandbox.md b/plugins/sql-fs/skills/py-sdk/ref/sandbox.md
index 2b9d40a..20f40ac 100644
--- a/plugins/sql-fs/skills/py-sdk/ref/sandbox.md
+++ b/plugins/sql-fs/skills/py-sdk/ref/sandbox.md
@@ -37,7 +37,7 @@ sb.record      # SandboxRecord | None — full record at creation; None if attac
 
 ## Exec
 
-### `sb.exec(script, *, cwd=None, env=None, timeout_ms=30_000, debug=False, read_only=False) -> ExecResult`
+### `sb.exec(script, *, cwd=None, env=None, timeout_ms=30_000, debug=False, read_only=False, retry_on_5xx=False) -> ExecResult`
 
 Buffered bash execution. Maps to `POST /v1/sandboxes/{id}/exec-sync`. Blocks
 until the script exits and returns a flat `ExecResult` with
@@ -51,6 +51,7 @@ result = sb.exec(
     timeout_ms=15_000,            # 1 ≤ ms ≤ 300_000
     debug=False,                  # True = prepend `set -x` for tracing
     read_only=False,              # True = skip exclusive lock; raises ValidationError on any write
+    retry_on_5xx=False,           # opt in to retrying transient 5xx on this write exec
 )
 print(result.stdout)              # str
 print(result.error)               # alias for .stderr
@@ -61,10 +62,13 @@ The SDK sets the underlying httpx timeout to `timeout_ms / 1000 + 5 s`, so a
 genuine server-side timeout surfaces as `ExecTimeoutError` (HTTP 408), not as a
 client-side network timeout.
 
-**Idempotency:** `exec` is **not** retried automatically (the server cannot
-safely re-execute a script). Wrap your own retry logic if needed.
+**Idempotency:** by default `exec` is **not** retried (the server cannot safely
+re-execute an arbitrary write script). It *is* retried on transient 5xx when
+`read_only=True` (always safe) or when you opt in with `retry_on_5xx=True` —
+set the latter only when the script is idempotent, since a retried write that
+already committed to Postgres would run twice.
 
-### `sb.exec_batch(scripts, *, timeout_ms=30_000, per_script_timeout_ms=None, read_only=False) -> list[BatchExecResult]`
+### `sb.exec_batch(scripts, *, timeout_ms=30_000, per_script_timeout_ms=None, read_only=False, retry_on_5xx=False) -> list[BatchExecResult]`
 
 Maps to `POST /v1/sandboxes/{id}/exec-sync-batch`. Run up to **50 scripts
 sequentially** (or in parallel when `read_only=True`) in one HTTP round-trip.
@@ -75,7 +79,7 @@ results = sb.exec_batch(
     [
         {"id": "tree", "script": "find /home/user -type f | head -20"},
         {"id": "imports", "script": "grep -rn '^from langgraph' /home/user | head -10"},
-        {"id": "uname", "script": "uname -srm"},
+        {"id": "count", "script": "find /home/user -type f | wc -l"},
     ],
     timeout_ms=60_000,            # outer ceiling covering the whole batch
     per_script_timeout_ms=5_000,  # each script independently limited to 5 s
@@ -139,7 +143,7 @@ overhead per chunk.
 
 ## Ingest (bootstrap only)
 
-### `sb.ingest_files(files, *, base_path="/home/user/project") -> dict`
+### `sb.ingest_files(files, *, base_path="/home/user/project", allow_oversized=False) -> dict`
 
 Maps to `POST /v1/sandboxes/{id}/ingest-files`. **Allowed for one-time
 bootstrap of a fresh sandbox** — for any further file mutation, switch to
@@ -171,6 +175,26 @@ checked against the client's `max_file_size` (default 64 MiB — see
 `ValidationError(code="EFILE_TOO_LARGE")` and **nothing is sent**. Raise or
 disable it with `Client(max_file_size=...)` / `max_file_size=0`.
 
+**8 MiB `python3` read limit (client-side).** Any file larger than 8 MiB raises
+`ValidationError(code="EFILE_TOO_LARGE_FOR_CPYTHON")` and **nothing is sent**.
+The `python3` runtime (CPython WASM) reads sandbox files through an 8 MiB IPC
+bridge — `open()` on a larger file fails with an opaque error. The bytes
+themselves ingest fine and stay usable from bash (`cat`/`grep`/`awk`) and
+`js-exec`; only `python3 open()` can't read them. Pass `allow_oversized=True` to
+ingest anyway (accepting that `python3` can't read the file), or split the file
+into <8 MiB chunks and recombine them in your script:
+
+```python
+# Blocked — a 17 MB CSV the python3 runtime can't open():
+sb.ingest_files({"data.csv": big_csv_bytes})           # raises EFILE_TOO_LARGE_FOR_CPYTHON
+
+# Option A — store it anyway for bash/js-exec (grep/awk/cut), not python3:
+sb.ingest_files({"data.csv": big_csv_bytes}, allow_oversized=True)
+
+# Option B — split into <8 MiB chunks, recombine in python3 (see SKILL.md):
+sb.ingest_files({"chunk1.csv": part1, "chunk2.csv": part2, "chunk3.csv": part3})
+```
+
 **Hard limits to keep in mind:**
 - All file bytes are buffered into one HTTP request body. The server caps the
   whole body (default 256 MB); after ~33% base64 inflation that's ~190 MB of raw
diff --git a/plugins/sql-fs/skills/ts-sdk/SETUP.md b/plugins/sql-fs/skills/ts-sdk/SETUP.md
new file mode 100644
index 0000000..5e12e3c
--- /dev/null
+++ b/plugins/sql-fs/skills/ts-sdk/SETUP.md
@@ -0,0 +1,193 @@
+# SQL-FS TypeScript SDK — Setup & Auth
+
+## Install
+
+The SDK lives at `clients/typescript/` in the sqlfs monorepo and is published as
+the `sql-fs-sdk` package on npm (see `package.json` for the canonical version).
+
+```bash
+# From npm (when released)
+npm install sql-fs-sdk
+
+# From this repo (workspace / file install — picks up local changes)
+pnpm add ./clients/typescript
+```
+
+ESM-only. Requires **Node ≥ 22** (the SDK uses the global `fetch`). No runtime
+dependencies.
+
+---
+
+## Two ways to authenticate
+
+The SDK accepts **either** a pre-minted `token` **or** the server's `authSecret`
+(plus a `sub`). The latter is recommended for short-lived agents — the SDK
+exchanges the secret for a JWT lazily on the first request.
+
+### Option A — `authSecret` (recommended for agents)
+
+```typescript
+import { Client } from "sql-fs-sdk";
+
+const client = new Client({
+  baseUrl: process.env.BASE_URL!,
+  authSecret: process.env.AUTH_SECRET!,
+  sub: "my-agent",            // token subject = sandbox owner identity
+  expiresIn: "30d",           // one of: "24h", "30d", "1y", "never"
+});
+
+console.log((await client.getToken()).slice(0, 20), "...");  // forces bootstrap
+```
+
+The bootstrap call hits `POST /v1/auth/bootstrap` with `X-Auth-Secret`. Subsequent
+requests reuse the cached JWT. `client.token` is the sync getter (may be
+`undefined` before bootstrap); `await client.getToken()` forces it.
+
+### Option B — pre-minted `token`
+
+If you've already minted a token (e.g. via `pnpm token:create` on the server
+host, or via `POST /v1/auth/admin`), pass it directly:
+
+```typescript
+const client = new Client({ baseUrl: process.env.BASE_URL!, token: process.env.TOKEN! });
+const sandboxes = await client.sandboxes.list();
+```
+
+You don't need `sub` when passing `token` — it's already encoded in the JWT.
+
+### Option C — admin secret (for token-minting tools, not agents)
+
+```typescript
+const client = new Client({
+  baseUrl: process.env.BASE_URL!,
+  adminSecret: process.env.ADMIN_SECRET!,
+  sub: "agent-001",
+});
+console.log(await client.getToken());  // minted via POST /v1/auth/admin
+```
+
+This is what you'd use to **build** a tool that mints scoped tokens for other
+agents. For day-to-day agent work, prefer Option A.
+
+---
+
+## Required env vars
+
+```bash
+export BASE_URL="<YOUR_BASE_URL>"          # e.g. https://your-app.azurecontainerapps.io
+export AUTH_SECRET="<YOUR_AUTH_SECRET>"   # never commit; ask the deployer
+# OR
+export TOKEN="<your-pre-minted-jwt>"
+```
+
+The SDK reads these via `process.env[...]` in your code — it does NOT read them
+automatically. Always pass them explicitly to `new Client({...})`.
+
+---
+
+## First sandbox — end-to-end smoke test
+
+```typescript
+import { Client } from "sql-fs-sdk";
+
+const client = new Client({
+  baseUrl: process.env.BASE_URL!,
+  authSecret: process.env.AUTH_SECRET!,
+  sub: "smoke",
+});
+
+const sb = await client.sandboxes.create({ name: "smoke-test" });
+try {
+  const result = await sb.exec("echo hello && pwd");
+  if (!result.ok) throw new Error(`unexpected exit ${result.exitCode}: ${result.error}`);
+  console.log(result.stdout);
+} finally {
+  await client.sandboxes.delete(sb.id);
+  client.close();
+}
+```
+
+---
+
+## Patterns to bake in
+
+### Always `client.close()` in a `finally`
+
+`Client.close()` releases the transport. There's no context-manager equivalent
+in TS — wrap the whole flow in `try/finally`:
+
+```typescript
+const client = new Client({ ... });
+try {
+  // ... work ...
+} finally {
+  client.close();
+}
+```
+
+### Always use `try/finally` around sandbox lifetime
+
+Sandboxes are durable — they survive process exit and accumulate Postgres rows
+(and storage) until explicitly deleted.
+
+```typescript
+const sb = await client.sandboxes.create({ name: "..." });
+try {
+  // ... do work ...
+} finally {
+  await client.sandboxes.delete(sb.id);   // or: await sb.delete()
+}
+```
+
+### Re-using an existing sandbox by id
+
+```typescript
+const sb = client.sandboxes.attach("550e8400-e29b-41d4-a716-446655440000");
+// .attach() does NOT hit the network — call .get(id) first if you need to verify.
+const info = await client.sandboxes.get(sb.id);
+console.log(info.lastUsedAt);
+```
+
+---
+
+## Multi-tenant deployments
+
+Pass `tenant` alongside `authSecret` to mint a tenant-scoped JWT:
+
+```typescript
+const client = new Client({
+  baseUrl: process.env.BASE_URL!,
+  authSecret: process.env.AUTH_SECRET!,
+  sub: "agent-1",
+  tenant: "tenant-a",
+});
+```
+
+For single-tenant deployments (most common), omit `tenant` entirely — the
+server falls back to the default tenant.
+
+---
+
+## Common setup mistakes
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| `Error: Provide one of: token, authSecret, or adminSecret` | Constructor called with no credentials | Pass exactly one of the three |
+| `Error: 'sub' is required when bootstrapping a token from a secret` | `authSecret` without `sub` | Add `sub: "..."` |
+| `AuthError` with `status === 401`, `code === "AUTH_INVALID"` | JWT expired, or `AUTH_SECRET` mismatch | Re-mint with correct secret |
+| `AuthError` with `status === 403`, `code === "FORBIDDEN"` | Accessing a sandbox owned by a different `sub` | Use the `sub` that created the sandbox, or attach via that token |
+| `RateLimitError` with `retryAfter` on bootstrap | `/v1/auth/bootstrap` rate limit (default 5 / 60s per IP) | Wait `retryAfter` seconds; or pass a pre-minted `token` instead of bootstrapping each run |
+| `TransportError: network error after N attempts` | Wrong `baseUrl`, DNS failure, or server down | Check `curl -fsS $BASE_URL/healthz` first |
+
+---
+
+## Verifying the deployment
+
+```typescript
+const r = await fetch(`${process.env.BASE_URL}/healthz`);
+if (!r.ok) throw new Error(`health check failed: ${r.status}`);
+console.log(await r.json());  // → { status: "ok" }
+```
+
+The SDK doesn't expose `/healthz` (it's not under `/v1`). Use global `fetch`
+directly when you just need to check liveness without auth.
diff --git a/plugins/sql-fs/skills/ts-sdk/SKILL.md b/plugins/sql-fs/skills/ts-sdk/SKILL.md
new file mode 100644
index 0000000..7a1e32e
--- /dev/null
+++ b/plugins/sql-fs/skills/ts-sdk/SKILL.md
@@ -0,0 +1,228 @@
+---
+name: ts-sdk
+description: "Expert operator of the SQL-FS TypeScript SDK (`sql-fs-sdk` package). Use when interacting with a live SQL-FS deployment from TypeScript/JavaScript: auth bootstrap, creating sandboxes, ingesting code, executing bash, streaming output, batching exploration. Triggers on: sqlfs typescript, sql-fs-sdk, ts sandbox, ingestFiles, sqlfs Client ts, sb.exec ts, execBatch."
+user-invocable: true
+---
+
+You are an expert operator of the **SQL-FS TypeScript SDK** — the `sql-fs-sdk`
+package that wraps the SQL-FS HTTP API in idiomatic TypeScript (`Client`,
+`Sandbox`, `ExecResult`, typed errors, async SSE streaming).
+Your job is to help the user write working, copy-pasteable TypeScript that talks
+to a live SQL-FS deployment.
+
+## How to use this skill
+
+Invoke with optional sub-commands:
+
+| Invocation | What happens |
+|---|---|
+| `/sql-fs:ts-sdk` | General assistant — answer questions, generate snippets |
+| `/sql-fs:ts-sdk setup` | Walk through install, env vars, first sandbox |
+| `/sql-fs:ts-sdk exec <script>` | Generate a ready-to-run `sb.exec(...)` snippet for `$ARGUMENTS` |
+| `/sql-fs:ts-sdk ingest <path>` | Generate an `sb.ingestFiles(...)` snippet for a local directory |
+| `/sql-fs:ts-sdk explore` | Build an `execBatch` exploration script for the active sandbox |
+
+Current arguments: **$ARGUMENTS**
+
+---
+
+## Package
+
+```
+npm install sql-fs-sdk                  # from npm (when published)
+pnpm add ./clients/typescript               # from this monorepo
+```
+
+ESM-only, requires Node ≥ 22 (uses global `fetch`). No runtime dependencies.
+
+Public surface:
+
+```typescript
+import {
+  Client, SandboxesResource, Sandbox, FilesAPI,         // entry points
+  type ClientOptions, type CreateSandboxOptions,
+  type ExecResult, type BatchExecResult, type StreamEvent,
+  type SandboxRecord, type SandboxInfo, type TreeEntry, ReadResult, type FileStat,
+  type ExecOptions, type ExecBatchOptions, type ExecBatchScript,
+  type ExecStreamOptions, type FileContent,
+  SQLFSError, AuthError, NotFoundError,
+  ConflictError, ValidationError, ExecTimeoutError,
+  RateLimitError, ServerError, TransportError,
+  version,
+} from "sql-fs-sdk";
+```
+
+Source lives at `clients/typescript/src/`.
+
+---
+
+## Deployment
+
+```
+BASE_URL     = <YOUR_BASE_URL>          (read from env, never hardcode)
+AUTH_SECRET  = <YOUR_AUTH_SECRET>       (read from env)
+TOKEN        = <pre-minted JWT>         (alternative to AUTH_SECRET)
+```
+
+Auth: the SDK lazily exchanges `authSecret` for a JWT on first request. Pass
+either `authSecret` (with `sub`) or a pre-minted `token`.
+
+---
+
+## Supporting docs — read these when relevant
+
+All reference material lives under `plugins/sql-fs/skills/ts-sdk/` in this project:
+
+- **Setup & auth** → `plugins/sql-fs/skills/ts-sdk/SETUP.md`
+  Read this when the user asks about install, env vars, token vs authSecret, or first-time setup.
+
+- **Client reference** → `plugins/sql-fs/skills/ts-sdk/ref/client.md`
+  `new Client({...})` + `client.sandboxes.{list,create,get,attach,delete}`. Read this for sandbox lifecycle.
+
+- **Sandbox reference** → `plugins/sql-fs/skills/ts-sdk/ref/sandbox.md`
+  `sb.exec / execBatch / execStream`, `sb.ingestFiles`, `sb.delete`. Read this for everything an agent does inside a sandbox.
+
+- **Models reference** → `plugins/sql-fs/skills/ts-sdk/ref/models.md`
+  Field-by-field shape of `ExecResult`, `BatchExecResult`, `StreamEvent`, `SandboxRecord`, etc. Read this when shaping return-value handling.
+
+- **Error reference** → `plugins/sql-fs/skills/ts-sdk/ref/errors.md`
+  Error class hierarchy + HTTP-status mapping. Read this when writing `try/catch` blocks.
+
+- **Working examples** → `plugins/sql-fs/skills/ts-sdk/examples/`
+  - `quickstart.ts` — create sandbox, exec, clean up
+  - `ingest-explore.ts` — load a codebase via `ingestFiles` then explore via `execBatch`
+  - `exec-stream.ts` — SSE streaming with proper `for await` iteration
+  - `batch-explore.ts` — agent exploration pattern (one round-trip, many probes)
+
+Read the relevant file(s) before answering so your responses use the exact
+method names, parameter spellings, and known gotchas from the SDK.
+
+---
+
+## Core rules
+
+1. **Always parameterise** via `process.env.BASE_URL` / `process.env.AUTH_SECRET`.
+   Never hardcode URLs or secrets in generated snippets.
+2. **Always call `client.close()`** in a `finally` block — it releases the
+   transport. There is no context-manager equivalent; use `try/finally`.
+3. **Always wrap sandbox use in `try/finally`** with `client.sandboxes.delete(sb.id)`
+   (or `sb.delete()`) in the finally block — sandboxes survive process exit and accumulate.
+4. **Sandbox filesystem is durable** (Postgres-backed). Bash session state (env vars,
+   cwd, shell functions) resets after 10 min idle — re-export anything you need.
+5. **For any task that runs scripts**: read `plugins/sql-fs/skills/ts-sdk/ref/sandbox.md`
+   first to use the right method and timeout shape.
+
+---
+
+## Method policy — exec-only sandbox interaction
+
+This mirrors the `api` skill's policy, applied to SDK method names. **All
+read / write / list interaction with a live sandbox MUST go through the exec
+methods (`sb.exec`, `sb.execBatch`, `sb.execStream`).** The `sb.fs.*`
+methods are banned for agent use.
+
+| Allowed | Banned |
+|---|---|
+| `client.sandboxes.create(...)` (incl. `files` seed at creation) | `sb.fs.read(path)` / `sb.fs.readText(path)` |
+| `client.sandboxes.get(id)` / `attach(id)` / `list()` | `sb.fs.write(path, content)` |
+| `client.sandboxes.delete(id)` / `sb.delete()` | `sb.fs.writeFiles({...})` |
+| `sb.exec(script, ...)` | `sb.fs.delete(path, ...)` |
+| `sb.execBatch([...])` | `sb.fs.mkdir(path, ...)` |
+| `sb.execStream(script, ...)` | `sb.fs.tree(...)` |
+| `sb.ingestFiles({...})` (one-time bootstrap only — see note) | |
+
+**Translate `fs.*` patterns to exec scripts:**
+
+| Need | Don't use | Use instead |
+|---|---|---|
+| Read a text file | `sb.fs.readText(path)` | `(await sb.exec("cat " + q(path))).stdout` |
+| Read binary safely | `sb.fs.read(path)` | `sb.exec("base64 " + q(path))` then `Buffer.from(r.stdout, "base64")` |
+| Write a small text file | `sb.fs.write(path, "...")` | `sb.exec("cat > " + q(path) + " <<'EOF'\n...\nEOF\n")` (single-quoted heredoc) |
+| Write binary | `sb.fs.write(path, bytes)` | base64-encode in JS, `sb.exec("echo '" + b64 + "' \| base64 -d > " + path)` |
+| Bulk write text | `sb.fs.writeFiles({...})` | One `sb.exec(...)` with multiple heredocs, OR `sb.ingestFiles({...})` if it's bootstrap |
+| Make a directory | `sb.fs.mkdir(path, { recursive: true })` | `sb.exec("mkdir -p " + q(path))` |
+| Delete a file/dir | `sb.fs.delete(path, { recursive: true })` | `sb.exec("rm -rf " + q(path))` |
+| List the tree | `sb.fs.tree({ prefix })` | `sb.exec("find " + root + " -printf '%y %s %p\\n'")` (or `ls -laR`, `stat`) |
+| Download as archive | (no fs method) | `(await sb.exec("tar -czf - " + root + " \| base64")).stdout` then decode client-side |
+
+`q()` is a shell-quoting helper — there is no built-in `shlex` in JS. Use a small
+helper or a library such as `shell-quote`:
+
+```typescript
+const q = (s: string) => `'${s.replace(/'/g, "'\\''")}'`;
+```
+
+**Ingest exception:** `sb.ingestFiles({...})` is allowed for one-time bulk bootstrapping
+a local folder into a fresh sandbox (single HTTP round-trip, base64-safe for binary).
+After ingest, all further interaction must be via `sb.exec / execBatch / execStream`.
+
+**Per-file size limits (client-side):** every write path (`ingestFiles`, `fs.write`,
+`fs.writeFiles`) enforces `new Client({ maxFileSize })` — default **64 MiB** —
+**before** anything is encoded or sent. An oversized file raises
+`ValidationError` (code `EFILE_TOO_LARGE`) client-side (no network round-trip).
+Additionally, `ingestFiles` rejects any file **> 8 MiB** with
+`ValidationError` (code `EFILE_TOO_LARGE_FOR_CPYTHON`) because the `python3`
+runtime (CPython WASM) can't `open()` it; pass `{ allowOversized: true }` to
+ingest anyway (the bytes stay usable from bash/`js-exec`). See `ref/client.md`
+and `ref/sandbox.md`.
+
+When a user asks for an `sb.fs.*` snippet, **decline politely and produce the exec
+equivalent instead**, citing this policy. If the workflow truly cannot be expressed
+via exec (e.g. streaming a 100 MB binary download to disk), surface that as a
+question rather than silently using a banned method.
+
+---
+
+## Atomicity — read-modify-write must be one script
+
+The sandbox lock is held for the **entire duration of one `exec` call**, then released. Two separate calls are two separate lock acquisitions. Another agent can slip in between them:
+
+```typescript
+// WRONG — race condition
+const balance = Number((await sb.exec("cat balance.txt")).stdout);
+// ← another agent can write here
+await sb.exec(`echo ${balance - 50} > balance.txt`);  // may silently overwrite their change
+```
+
+```typescript
+// CORRECT — entire operation inside one lock acquisition
+await sb.exec("balance=$(cat balance.txt); echo $((balance - 50)) > balance.txt");
+```
+
+**Rule:** if you read state and then write based on it, the read, compute, and write must all be in a single bash script string. Any JS logic between two `exec` calls is outside the lock.
+
+`execBatch` acquires the lock **once for the whole batch** — scripts within a batch are safe relative to each other. The same caveat applies between two separate `execBatch` calls.
+
+## Performance heuristics
+
+These mirror the Python SDK benchmarks (`clients/python/examples/perf_benchmark.py`); the wire behaviour is identical:
+
+- **`execBatch` >> N × `exec`.** Each `exec-sync` round-trip is ~700 ms steady-state
+  even for `:` (no-op). Bundling 50 trivial probes into one `execBatch` call costs
+  about the same wall-clock as a single `exec`, ~14 ms/script effectively. Always
+  batch independent exploration probes (find + grep + cat + wc + …) into one call.
+
+- **`pathCache` is hot, `contentCache` is cold.** Commands that only read inode
+  metadata (`find`, `ls`, `stat`, `wc -c`) are cheap. The first command that opens
+  every file's bytes (`grep -r`, `cat`, `awk`) pays one DB round-trip per blob —
+  ~50 ms × N files of cold tax. After that, the in-process LRU is hot. Tip: if a
+  caller knows up-front which files matter, prefer `find ... | head` or
+  `grep ... | head -N` so SIGPIPE short-circuits before scanning the whole tree.
+
+- **`ingestFiles` is the right way to upload a codebase**, not per-file `fs.write`.
+  Per-file writes pay one HTTP round-trip + one transaction per file (seconds for
+  even 50 files). `ingestFiles` is one HTTP, base64 inflation ~33%, no per-file
+  TLS overhead.
+
+- **`sb.exec` is reusable**, not per-call. The session manager keeps the just-bash
+  worker warm for 10 min idle. Repeated `sb.exec(...)` calls reuse the same Bash
+  process — cwd, env vars, and shell functions persist within that window.
+
+- **Batch multi-step Python into one `python3` script, not many `python3 -c` calls.**
+  On `python: true` sandboxes, `python3` is CPython-on-WASM, stdlib only, and each
+  call cold-boots a fresh isolated interpreter (~1.4 s, no shared state). Write
+  your logic to a file and run `python3 script.py` once rather than looping
+  `python3 -c '...'` — one script with a loop avoids paying the cold-boot N times.
+  Persist data across calls via the sandbox filesystem, not interpreter state.
+
+6. Pass `{ readOnly: true }` on `sb.exec`, `sb.execBatch`, and `sb.execStream` whenever the script only reads data (grep, cat, find, wc, stat, etc.). This skips the exclusive sandbox write-lock, allowing concurrent reads from multiple callers. Any mutating filesystem op in a read-only script raises `ValidationError` (code `EREADONLY_VIOLATION`).
diff --git a/plugins/sql-fs/skills/ts-sdk/examples/batch-explore.ts b/plugins/sql-fs/skills/ts-sdk/examples/batch-explore.ts
new file mode 100644
index 0000000..ec6120e
--- /dev/null
+++ b/plugins/sql-fs/skills/ts-sdk/examples/batch-explore.ts
@@ -0,0 +1,67 @@
+/**
+ * Agent exploration via execBatch — one round-trip, many probes.
+ *
+ * This is the canonical pattern for an LLM agent doing initial code reconnaissance
+ * on a freshly-ingested sandbox. Each probe is independent, so they run as one
+ * batch — wall-clock cost is the cost of a single round-trip.
+ *
+ * Compare:
+ *   - 8 individual `sb.exec(...)` calls: ~8 × 700 ms = ~5.6 s
+ *   - 1 `sb.execBatch([...])` with 8 scripts: ~700 ms
+ *
+ * Run with:
+ *   BASE_URL=... AUTH_SECRET=... SANDBOX_ID=... npx tsx batch-explore.ts
+ *   # (assumes the sandbox is already populated by ingest-explore.ts)
+ */
+
+import { Client, type Sandbox } from "sql-fs-sdk";
+
+const SANDBOX_BASE = "/home/user/proj";
+
+async function explore(sb: Sandbox): Promise<Record<string, string>> {
+	const probes: Record<string, string> = {
+		tree: `find ${SANDBOX_BASE} -type f | head -50`,
+		ts_count: `find ${SANDBOX_BASE} -name '*.ts' | wc -l`,
+		biggest: `find ${SANDBOX_BASE} -type f -printf '%s %p\\n' | sort -rn | head -5`,
+		imports: `grep -rhn '^import ' ${SANDBOX_BASE} 2>/dev/null | sort -u | head -30`,
+		exports: `grep -rn '^export ' ${SANDBOX_BASE} 2>/dev/null | head -15`,
+		todos: `grep -rn 'TODO\\|FIXME\\|XXX' ${SANDBOX_BASE} 2>/dev/null | head -10`,
+		entrypoints: `find ${SANDBOX_BASE} -maxdepth 3 -name 'index.ts' -o -name 'main.ts' -o -name 'server.ts'`,
+		pkg: `cat ${SANDBOX_BASE}/package.json 2>/dev/null | head -40`,
+	};
+	const results = await sb.execBatch(
+		Object.entries(probes).map(([id, script]) => ({ id, script })),
+		{ timeoutMs: 60_000, readOnly: true },
+	);
+	return Object.fromEntries(results.filter((r) => r.ok).map((r) => [r.id, r.stdout]));
+}
+
+async function main(): Promise<number> {
+	const sandboxId = process.env.SANDBOX_ID;
+	const client = new Client({
+		baseUrl: process.env.BASE_URL!,
+		authSecret: process.env.AUTH_SECRET!,
+		sub: "batch-explorer",
+	});
+	try {
+		if (!sandboxId) {
+			console.error("set SANDBOX_ID to an already-populated sandbox (see ingest-explore.ts)");
+			return 1;
+		}
+		const sb = client.sandboxes.attach(sandboxId);
+		console.log(`attached to ${sb.id}`);
+
+		const findings = await explore(sb);
+		for (const [id, stdout] of Object.entries(findings)) {
+			const preview = stdout.trimEnd().split("\n").slice(0, 6);
+			console.log(`\n[${id}]`);
+			for (const line of preview) console.log(`  ${line}`);
+		}
+		// Don't delete an attached sandbox — caller owns its lifecycle.
+	} finally {
+		client.close();
+	}
+	return 0;
+}
+
+process.exit(await main());
diff --git a/plugins/sql-fs/skills/ts-sdk/examples/exec-stream.ts b/plugins/sql-fs/skills/ts-sdk/examples/exec-stream.ts
new file mode 100644
index 0000000..4cb1eff
--- /dev/null
+++ b/plugins/sql-fs/skills/ts-sdk/examples/exec-stream.ts
@@ -0,0 +1,70 @@
+/**
+ * Streaming exec — consume stdout/stderr as it's produced.
+ *
+ * Use `sb.execStream(...)` when:
+ *   - the script produces output incrementally and you want it live (build logs)
+ *   - you want to short-circuit on a specific output pattern
+ *
+ * Otherwise prefer `sb.exec(...)` (buffered) — simpler, no SSE framing overhead.
+ *
+ * Run with:
+ *   BASE_URL=... AUTH_SECRET=... npx tsx exec-stream.ts
+ */
+
+import type { StreamEvent } from "sql-fs-sdk";
+import { Client } from "sql-fs-sdk";
+
+async function main(): Promise<number> {
+	const client = new Client({
+		baseUrl: process.env.BASE_URL!,
+		authSecret: process.env.AUTH_SECRET!,
+		sub: "streamer",
+	});
+	try {
+		const sb = await client.sandboxes.create({ name: "stream-demo" });
+		try {
+			const script = `
+				for i in 1 2 3 4 5; do
+				  echo "stdout line $i"
+				  if [ $i -eq 3 ]; then
+				    echo "warning at 3" >&2
+				  fi
+				  sleep 0.2
+				done
+			`;
+
+			let exitEvent: StreamEvent | undefined;
+
+			// The generator closes the underlying connection automatically on
+			// the exit event OR when you `break` out — so it's safe to short-circuit.
+			for await (const ev of sb.execStream(script, { timeoutMs: 15_000 })) {
+				if (ev.type === "stdout") process.stdout.write(ev.data ?? "");
+				else if (ev.type === "stderr") process.stderr.write(`[stderr] ${ev.data}`);
+				else if (ev.type === "exit") exitEvent = ev;
+			}
+
+			if (exitEvent) {
+				console.log(`\n--- exit code=${exitEvent.exitCode} duration=${exitEvent.durationMs} ms ---`);
+			}
+
+			// Pattern: short-circuit the stream the moment a sentinel appears.
+			console.log("\n[short-circuit demo] stop streaming after 'STOP' line:");
+			for await (const ev of sb.execStream(
+				"for i in 1 2 3 4 5; do echo line-$i; done; echo STOP; sleep 5; echo never",
+				{ timeoutMs: 10_000 },
+			)) {
+				if (ev.type === "stdout") {
+					process.stdout.write(ev.data ?? "");
+					if ((ev.data ?? "").includes("STOP")) break; // generator's finally closes the connection
+				}
+			}
+		} finally {
+			await client.sandboxes.delete(sb.id);
+		}
+	} finally {
+		client.close();
+	}
+	return 0;
+}
+
+process.exit(await main());
diff --git a/plugins/sql-fs/skills/ts-sdk/examples/ingest-explore.ts b/plugins/sql-fs/skills/ts-sdk/examples/ingest-explore.ts
new file mode 100644
index 0000000..ecae3f3
--- /dev/null
+++ b/plugins/sql-fs/skills/ts-sdk/examples/ingest-explore.ts
@@ -0,0 +1,100 @@
+/**
+ * Bulk-ingest a local folder, then explore the codebase via execBatch.
+ *
+ * Demonstrates the canonical agent workflow:
+ *   1. ONE round-trip via `sb.ingestFiles(...)` to bootstrap the sandbox.
+ *   2. ALL subsequent reads/lists via `sb.execBatch([...])` (one round-trip).
+ *   3. Clean up.
+ *
+ * Compare wall-clock cost: per-file `fs.write` would cost N HTTP round-trips
+ * (seconds-per-file at typical RTT). `ingestFiles` is one round-trip regardless
+ * of file count.
+ *
+ * Run with:
+ *   BASE_URL=... AUTH_SECRET=... npx tsx ingest-explore.ts /path/to/local/code
+ */
+
+import { readFile, readdir } from "node:fs/promises";
+import path from "node:path";
+import { Client } from "sql-fs-sdk";
+
+const SANDBOX_BASE = "/home/user/proj";
+const SKIP_DIRS = new Set([".git", "node_modules", "dist", ".next", "__pycache__"]);
+const SKIP_NAMES = new Set([".DS_Store"]);
+
+async function collect(
+	root: string,
+	base = root,
+	out: Record<string, Uint8Array> = {},
+): Promise<Record<string, Uint8Array>> {
+	for (const entry of await readdir(root, { withFileTypes: true })) {
+		if (entry.isDirectory()) {
+			if (SKIP_DIRS.has(entry.name)) continue;
+			await collect(path.join(root, entry.name), base, out);
+		} else if (entry.isFile() && !SKIP_NAMES.has(entry.name)) {
+			const abs = path.join(root, entry.name);
+			const rel = path.relative(base, abs).split(path.sep).join("/");
+			out[rel] = await readFile(abs);
+		}
+	}
+	return out;
+}
+
+async function main(): Promise<number> {
+	const folder = process.argv[2];
+	if (!folder) {
+		console.error(`usage: ${process.argv[1]} <local-folder>`);
+		return 2;
+	}
+
+	console.log(`walking ${folder} ...`);
+	const files = await collect(path.resolve(folder));
+	const total = Object.values(files).reduce((n, b) => n + b.byteLength, 0);
+	console.log(`  ${Object.keys(files).length} files, ${total.toLocaleString()} bytes`);
+
+	const client = new Client({
+		baseUrl: process.env.BASE_URL!,
+		authSecret: process.env.AUTH_SECRET!,
+		sub: "ingest-explore",
+	});
+	try {
+		const sb = await client.sandboxes.create({ name: "ingest-explore" });
+		try {
+			let t = performance.now();
+			await sb.ingestFiles(files, { basePath: SANDBOX_BASE });
+			console.log(
+				`ingestFiles: ${Math.round(performance.now() - t)} ms ` +
+					`(${Object.keys(files).length} files, 1 HTTP round-trip)`,
+			);
+
+			// Build an exploration probe-set. Every probe runs in ONE batch
+			// round-trip. Add or trim freely — the batch endpoint handles up to
+			// 50 scripts and shares a single timeout budget.
+			const probes: Array<{ id: string; script: string }> = [
+				{ id: "tree", script: `find ${SANDBOX_BASE} -type f -printf '%s %p\\n' | sort -rn | head -10` },
+				{ id: "ts_count", script: `find ${SANDBOX_BASE} -name '*.ts' | wc -l` },
+				{ id: "imports", script: `grep -rhn '^import ' ${SANDBOX_BASE} 2>/dev/null | sort -u | head -20` },
+				{ id: "exports", script: `grep -rhn '^export ' ${SANDBOX_BASE} 2>/dev/null | head -15` },
+				{ id: "todos", script: `grep -rn 'TODO\\|FIXME' ${SANDBOX_BASE} 2>/dev/null | head -10` },
+				{ id: "entry", script: `find ${SANDBOX_BASE} -maxdepth 2 -name 'index.ts' -o -name 'main.ts' | head -5` },
+			];
+
+			t = performance.now();
+			const results = await sb.execBatch(probes, { timeoutMs: 60_000, readOnly: true });
+			console.log(`execBatch:   ${Math.round(performance.now() - t)} ms for ${probes.length} probes (1 round-trip)`);
+
+			for (const r of results) {
+				const head = r.stdout.trimEnd().split("\n").slice(0, 8);
+				console.log(`\n[${r.id}] exit=${r.exitCode}`);
+				for (const line of head) console.log(`  ${line}`);
+			}
+		} finally {
+			await client.sandboxes.delete(sb.id);
+		}
+	} finally {
+		client.close();
+	}
+	return 0;
+}
+
+process.exit(await main());
diff --git a/plugins/sql-fs/skills/ts-sdk/examples/quickstart.ts b/plugins/sql-fs/skills/ts-sdk/examples/quickstart.ts
new file mode 100644
index 0000000..4b2bd4d
--- /dev/null
+++ b/plugins/sql-fs/skills/ts-sdk/examples/quickstart.ts
@@ -0,0 +1,51 @@
+/**
+ * Quickstart — create a sandbox, exec a script, clean up.
+ *
+ * Run with:
+ *   BASE_URL=...  AUTH_SECRET=...  npx tsx quickstart.ts
+ */
+
+import { Client, ExecTimeoutError } from "sql-fs-sdk";
+
+async function main(): Promise<number> {
+	const baseUrl = process.env.BASE_URL;
+	const authSecret = process.env.AUTH_SECRET;
+	const token = process.env.TOKEN;
+	if (!baseUrl || !(authSecret || token)) {
+		console.error("set BASE_URL and either AUTH_SECRET or TOKEN");
+		return 2;
+	}
+
+	const client = new Client({ baseUrl, authSecret, token, sub: "quickstart" });
+	try {
+		const sb = await client.sandboxes.create({ name: "quickstart" });
+		console.log(`created sandbox ${sb.id}`);
+		try {
+			// Single buffered exec — get back a flat ExecResult.
+			const r = await sb.exec("echo hello && pwd");
+			if (!r.ok) {
+				console.error(`unexpected exit ${r.exitCode}: ${r.error}`);
+				return 1;
+			}
+			console.log(`--- stdout (exit=${r.exitCode}, ${r.durationMs} ms) ---`);
+			console.log(r.stdout);
+
+			// Demonstrate timeout handling — exec scripts that exceed timeoutMs
+			// surface as ExecTimeoutError, not as a failed-result row.
+			try {
+				await sb.exec("sleep 5", { timeoutMs: 1_000 });
+			} catch (e) {
+				if (e instanceof ExecTimeoutError) console.log(`(expected) timed out after ${e.durationMs} ms`);
+				else throw e;
+			}
+		} finally {
+			await client.sandboxes.delete(sb.id);
+			console.log(`deleted sandbox ${sb.id}`);
+		}
+	} finally {
+		client.close();
+	}
+	return 0;
+}
+
+process.exit(await main());
diff --git a/plugins/sql-fs/skills/ts-sdk/ref/client.md b/plugins/sql-fs/skills/ts-sdk/ref/client.md
new file mode 100644
index 0000000..92c4a01
--- /dev/null
+++ b/plugins/sql-fs/skills/ts-sdk/ref/client.md
@@ -0,0 +1,243 @@
+# `Client` reference
+
+The top-level entry point. Wraps a `fetch`-based transport with auth bootstrap,
+retry policy, and the typed error layer. One `Client` instance is safe for the
+lifetime of your process.
+
+```typescript
+import { Client } from "sql-fs-sdk";
+```
+
+---
+
+## Constructor
+
+```typescript
+new Client({
+  baseUrl: string,                  // required
+  token?: string,                   // one of these three is required
+  authSecret?: string,
+  adminSecret?: string,
+  sub?: string,                     // required if using authSecret/adminSecret
+  tenant?: string,                  // multi-tenant deployments only
+  expiresIn?: string,               // "24h" | "30d" | "1y" | "never" (default "30d")
+  timeout?: number,                 // default fetch timeout in ms (default 30_000)
+  maxRetries?: number,              // 5xx / 429 retries with jitter (default 3)
+  userAgent?: string,               // defaults to "sql-fs-sdk/<ver>"
+  fetch?: typeof globalThis.fetch,  // bring-your-own (e.g. for mocks)
+  maxFileSize?: number,             // per-file ceiling in bytes (default 64 MiB); 0 disables
+})
+```
+
+**Validation:** the constructor throws `Error` if you pass none of
+`token / authSecret / adminSecret`, or if you pass a secret without `sub`.
+
+**Token bootstrap is lazy.** Constructing the `Client` does not hit the network —
+the JWT is minted on the first request that needs it (or when you call
+`client.getToken()`).
+
+**`maxFileSize` (bytes, default 64 MiB).** A per-file ceiling enforced
+**client-side**, before any content is base64-encoded or sent over the network.
+It applies to every write path — `sb.ingestFiles(...)`, `sb.fs.write(...)`, and
+`sb.fs.writeFiles(...)`. A file larger than the limit throws `ValidationError`
+(code `EFILE_TOO_LARGE`) naming each offending path and its size; nothing is
+transmitted. The limit is threaded down to every `Sandbox` the client creates or
+attaches. Set `maxFileSize: 0` to disable the check entirely.
+
+```typescript
+new Client({ baseUrl, authSecret, sub: "agent", maxFileSize: 128 * 1024 * 1024 });  // raise to 128 MiB
+new Client({ baseUrl, authSecret, sub: "agent", maxFileSize: 0 });                  // disable
+```
+
+> The `maxFileSize` check is separate from the 8 MiB `python3` read limit that
+> `ingestFiles` enforces — see `ref/sandbox.md`. A file between 8 MiB and
+> `maxFileSize` ingests fine but can't be read by the `python3` runtime unless
+> you pass `{ allowOversized: true }`.
+
+> Sizing note: the server caps the whole HTTP request body (default 256 MB) and
+> base64 inflates content ~33%, so the practical per-request ceiling is ~190 MB
+> of raw bytes regardless of `maxFileSize`. The default 64 MiB keeps a single
+> file well inside that, with margin for batching several files in one ingest.
+
+---
+
+## Releasing resources
+
+There is no context manager in TS. Always call `client.close()` in a `finally`:
+
+```typescript
+const client = new Client({ baseUrl, token });
+try {
+  await client.sandboxes.list();
+} finally {
+  client.close();
+}
+```
+
+---
+
+## Properties & methods
+
+| Member | Type | Notes |
+|---|---|---|
+| `client.token` | `string \| undefined` | The current JWT, or `undefined` before bootstrap. Sync getter. |
+| `client.getToken()` | `Promise<string>` | Forces bootstrap from `authSecret`/`adminSecret` if needed, then returns the cached JWT. |
+| `client.close()` | `void` | Releases the transport. |
+
+---
+
+## `client.sandboxes` — sandbox CRUD
+
+A namespaced resource exposing the four sandbox lifecycle operations plus a
+zero-cost `attach()` for reusing an existing id.
+
+### `client.sandboxes.list(): Promise<SandboxRecord[]>`
+
+Maps to `GET /v1/sandboxes`. Returns sandboxes owned by the caller's `sub`.
+
+```typescript
+for (const s of await client.sandboxes.list()) {
+  console.log(s.id, s.name, s.createdAt);
+}
+```
+
+### `client.sandboxes.create(options?): Promise<Sandbox>`
+
+Maps to `POST /v1/sandboxes`. Returns a `Sandbox` handle bound to the new id,
+ready for `exec` / `ingestFiles`.
+
+```typescript
+const sb = await client.sandboxes.create({
+  name: "my-project",                       // human label, optional
+  env: { GREETING: "hi" },                   // initial sandbox env vars
+  files: { "/home/user/seed.txt": "..." },   // text-only seed (use ingestFiles for many/binary)
+  python: false,                             // enable CPython WASM runtime
+  javascript: false,                         // enable QuickJS runtime
+  network: false,                            // enable outbound fetch() from js-exec (opt-in)
+});
+```
+
+All options are optional — `client.sandboxes.create()` is valid and creates
+an anonymous sandbox.
+
+**`network: true` — enabling outbound fetch()**
+
+Pass `network: true` together with `javascript: true` to allow `fetch()` calls
+inside `js-exec` scripts to reach external HTTP endpoints:
+
+```typescript
+const sb = await client.sandboxes.create({ javascript: true, network: true });
+const r = await sb.exec(`js-exec -c '
+  fetch("https://httpbin.org/get")
+    .then(r => r.json())
+    .then(d => console.log("origin:", d.origin))
+'`);
+console.log(r.stdout);   // origin: <your-ip>
+```
+
+- **Bash remains air-gapped.** Even with `network: true`, the Bash shell has
+  no `curl`, `wget`, DNS, or raw socket access. Only `fetch()` inside `js-exec`
+  gains outbound HTTP.
+- **Opt-in, default `false`.** Omitting `network` (or passing `network: false`)
+  produces a fully isolated sandbox.
+- **js-exec timeout extends to 60 s** when network is enabled.
+
+### `client.sandboxes.get(sandboxId): Promise<SandboxInfo>`
+
+Maps to `GET /v1/sandboxes/{id}`. Use this when you have an id and need to
+verify ownership / read `lastUsedAt`. Throws `NotFoundError` (404) or
+`AuthError` (403) for a sandbox owned by a different `sub`.
+
+### `client.sandboxes.attach(sandboxId): Sandbox`
+
+**No network call. Synchronous.** Returns a `Sandbox` handle for an existing id.
+Use this to resume work on a long-lived sandbox without paying a `GET`
+round-trip. Combine with `.get()` if you need to verify the sandbox first.
+
+```typescript
+const sb = client.sandboxes.attach(process.env.SANDBOX_ID!);
+const result = await sb.exec("ls /home/user");
+```
+
+### `client.sandboxes.delete(sandboxId): Promise<void>`
+
+Maps to `DELETE /v1/sandboxes/{id}`. Destroys the sandbox and orphans its
+blobs (which are GC'd by the server's blob-GC job).
+
+```typescript
+await client.sandboxes.delete(sb.id);
+// Equivalent: await sb.delete();
+```
+
+Throws `NotFoundError` if the id doesn't exist or `AuthError` if owned by a
+different `sub`.
+
+---
+
+## Retry & error policy
+
+The `Client` retries up to `maxRetries` times on **transient** failures only:
+
+| Status | Retried? |
+|---|---|
+| 200–299 | n/a (success) |
+| 400 / 404 / 408 / 409 | **No** — surfaced immediately as typed errors |
+| 401 / 403 | **No** — surfaced immediately as `AuthError` |
+| 429 | **Yes** — honours `Retry-After` header if present, else exponential jitter |
+| 5xx | **Yes** — exponential jitter |
+| network (DNS, TCP, TLS, timeout) | **Yes** — exponential jitter |
+
+`exec` / `execBatch` are only retried when `readOnly` or `retryOn5xx` is set
+(otherwise the server can't safely re-run them). `execStream` is **never**
+retried — at-most-once semantics. After `maxRetries` exhaustion the SDK throws
+`ServerError` (for 5xx) or `TransportError` (for network failures).
+
+See `plugins/sql-fs/skills/ts-sdk/ref/errors.md` for the full error hierarchy.
+
+---
+
+## Common patterns
+
+### Long-lived agent process — keep one `Client`
+
+```typescript
+class Agent {
+  readonly client: Client;
+  constructor() {
+    this.client = new Client({
+      baseUrl: process.env.BASE_URL!,
+      authSecret: process.env.AUTH_SECRET!,
+      sub: "agent",
+    });
+  }
+  close() {
+    this.client.close();
+  }
+}
+```
+
+The bootstrap hits the wire once. Subsequent calls reuse the cached JWT.
+
+### Short-lived script — try/finally
+
+```typescript
+const client = new Client({ baseUrl, authSecret, sub: "cli" });
+try {
+  const sb = await client.sandboxes.create({ name: "cli-run" });
+  try {
+    // ...
+  } finally {
+    await client.sandboxes.delete(sb.id);
+  }
+} finally {
+  client.close();
+}
+```
+
+### Custom `fetch` (e.g. for tests, proxies, instrumentation)
+
+```typescript
+const client = new Client({ baseUrl, token, fetch: myInstrumentedFetch });
+```
+
+The SDK uses the supplied `fetch` for every request; it does not own or close it.
diff --git a/plugins/sql-fs/skills/ts-sdk/ref/errors.md b/plugins/sql-fs/skills/ts-sdk/ref/errors.md
new file mode 100644
index 0000000..0b0ce33
--- /dev/null
+++ b/plugins/sql-fs/skills/ts-sdk/ref/errors.md
@@ -0,0 +1,205 @@
+# Error reference
+
+All errors extend `SQLFSError`. Each carries the server's `code` (e.g. `ENOENT`),
+HTTP `status`, and any `details`.
+
+```typescript
+import {
+  SQLFSError,
+  AuthError,
+  NotFoundError,
+  ConflictError,
+  ValidationError,
+  ExecTimeoutError,
+  RateLimitError,
+  ServerError,
+  TransportError,
+} from "sql-fs-sdk";
+```
+
+---
+
+## Hierarchy
+
+```
+SQLFSError                    base — never thrown directly by the SDK
+├── AuthError                     401 / 403
+├── NotFoundError                 404
+├── ConflictError                 409 (EEXIST, ENOTEMPTY)
+├── ValidationError               400 (INVALID_INPUT, EISDIR, ENOTDIR, EINVAL, ELOOP);
+│                                 also client-side EFILE_TOO_LARGE / EFILE_TOO_LARGE_FOR_CPYTHON;
+│                                 also EREADONLY_VIOLATION (422) from a write in a readOnly exec
+├── ExecTimeoutError              408 (script ran longer than timeoutMs)
+├── RateLimitError                429
+├── ServerError                   5xx after retries exhausted
+└── TransportError                network failure (DNS, TCP, TLS, timeout)
+```
+
+Every error is an `instanceof SQLFSError`, so a single `catch (e) { if (e instanceof SQLFSError) ... }`
+covers them all.
+
+---
+
+## HTTP → error mapping
+
+| HTTP | Class | Common server `code` | Cause |
+|------|-------|---------------------|-------|
+| 400 | `ValidationError` | `INVALID_INPUT`, `EISDIR`, `ENOTDIR`, `EINVAL`, `ELOOP` | Body/query validation, or path semantics (e.g. reading a dir as a file) |
+| 401 | `AuthError` | `AUTH_REQUIRED`, `AUTH_INVALID`, `AUTH_UNKNOWN_TENANT` | Missing/expired token, wrong `AUTH_SECRET`, unknown tenant |
+| 403 | `AuthError` | `FORBIDDEN` | Sandbox owned by a different `sub`; admin endpoint without `X-Admin-Secret` |
+| 404 | `NotFoundError` | `ENOENT` | Sandbox/file/dir not found, or sandbox already deleted |
+| 408 | `ExecTimeoutError` | `EXEC_TIMEOUT` | Script exceeded `timeoutMs` |
+| 409 | `ConflictError` | `EEXIST`, `ENOTEMPTY` | Path collision; non-empty dir without `recursive: true` |
+| 422 | `ValidationError` | `EREADONLY_VIOLATION` | A write op ran in a `readOnly` exec/stream |
+| 429 | `RateLimitError` | `RATE_LIMITED` | Bootstrap/admin endpoint rate limit (default 5 / 60s) |
+| 5xx | `ServerError` | `INTERNAL_ERROR`, `ESESSIONCLOSING`, `ELOCKTIMEOUT`, `ELOCKLOST` | Server failure after retries exhausted |
+| network | `TransportError` | n/a | DNS, TCP, TLS, timeout |
+
+The SDK retries 429 / 5xx / network failures up to `maxRetries` (default 3)
+with exponential jitter. The error you catch is the **final** failure.
+
+---
+
+## Client-side validation (thrown before any HTTP request)
+
+Not every `ValidationError` comes from the server. The SDK enforces two
+per-file ceilings locally on `ingestFiles`, so an oversized file fails
+**before** anything is base64-encoded or sent:
+
+| `code` | Thrown by | Cause |
+|---|---|---|
+| `EFILE_TOO_LARGE` | `ingestFiles`, `fs.write`, `fs.writeFiles` | A file exceeds the client's `maxFileSize` (default 64 MiB). `e.status` is `undefined`; `e.details` lists each offending `path (size > limit)`. Disable with `maxFileSize: 0`. |
+| `EFILE_TOO_LARGE_FOR_CPYTHON` | `ingestFiles` | A file exceeds **8 MiB**, which the `python3` runtime (CPython WASM) can't `open()`. `e.status` is `undefined`; `e.details` lists each offending path. Pass `{ allowOversized: true }` to ingest anyway (usable from bash/`js-exec`, not `python3`), or split into <8 MiB chunks. |
+
+```typescript
+import { ValidationError } from "sql-fs-sdk";
+
+try {
+  await sb.ingestFiles({ "huge.csv": payload });
+} catch (e) {
+  if (e instanceof ValidationError && e.code === "EFILE_TOO_LARGE_FOR_CPYTHON") {
+    // too big for python3, never sent. Retry with { allowOversized: true } if
+    // you only need it from bash, or chunk it.
+    await sb.ingestFiles({ "huge.csv": payload }, { allowOversized: true });
+  }
+}
+```
+
+---
+
+## Common properties
+
+Every error exposes:
+
+| Property | Type | Notes |
+|---|---|---|
+| `e.code` | `string \| undefined` | Server-side machine code (`ENOENT`, `RATE_LIMITED`, …) or client-side code |
+| `e.status` | `number \| undefined` | HTTP status code; `undefined` for client-side / transport errors |
+| `e.details` | `unknown` | Server's `details` array, if any |
+
+Some errors add fields:
+
+| Class | Extra | Notes |
+|---|---|---|
+| `ExecTimeoutError` | `e.durationMs?: number` | Wall-clock spent before timeout |
+| `RateLimitError` | `e.retryAfter?: number` | Seconds from the `Retry-After` response header |
+
+---
+
+## Idiomatic `try/catch` patterns
+
+### Catch a specific failure mode
+
+```typescript
+import { NotFoundError } from "sql-fs-sdk";
+
+let info: SandboxInfo | null = null;
+try {
+  info = await client.sandboxes.get(sbId);
+} catch (e) {
+  if (e instanceof NotFoundError) info = null;  // deleted out from under us
+  else throw e;
+}
+```
+
+### Distinguish auth from authz
+
+`AuthError` covers both 401 and 403 — check `.status` to disambiguate:
+
+```typescript
+import { AuthError } from "sql-fs-sdk";
+
+try {
+  await client.sandboxes.list();
+} catch (e) {
+  if (e instanceof AuthError) {
+    if (e.status === 401) console.log("token expired or invalid — re-authenticate");
+    else if (e.status === 403) console.log("forbidden:", e.details);
+  } else throw e;
+}
+```
+
+### Honour `retryAfter` on rate limit
+
+```typescript
+import { RateLimitError } from "sql-fs-sdk";
+
+try {
+  await client.sandboxes.create({ name: "x" });
+} catch (e) {
+  if (e instanceof RateLimitError) {
+    await new Promise((r) => setTimeout(r, (e.retryAfter ?? 5) * 1000));
+    await client.sandboxes.create({ name: "x" });
+  } else throw e;
+}
+```
+
+In practice the SDK already retries 429 transparently; you only see this error
+when retries are exhausted.
+
+### Distinguish exec timeout from server-side bash failure
+
+`ExecTimeoutError` is thrown when the **server** kills the script for exceeding
+`timeoutMs`. A script that exits non-zero on its own is **not** an error — it's
+a successful HTTP response with `exitCode !== 0`. Check `result.ok`:
+
+```typescript
+import { ExecTimeoutError } from "sql-fs-sdk";
+
+try {
+  const r = await sb.exec("long-running-script.sh", { timeoutMs: 10_000 });
+  if (!r.ok) console.log(`script exited ${r.exitCode}: ${r.error}`);
+} catch (e) {
+  if (e instanceof ExecTimeoutError) console.log(`timed out after ${e.durationMs}ms`);
+  else throw e;
+}
+```
+
+### Catch-all at the top of an agent loop
+
+```typescript
+import { SQLFSError } from "sql-fs-sdk";
+
+try {
+  await doWork(sb);
+} catch (e) {
+  if (e instanceof SQLFSError) {
+    log.error("sqlfs failure", { code: e.code, status: e.status, details: e.details });
+  } else throw e;
+}
+```
+
+Catching `SQLFSError` covers every typed error the SDK can throw. Bare `fetch`
+failures are wrapped into `TransportError` before they surface, so you don't
+need a separate network-error branch.
+
+---
+
+## What the SDK does NOT throw
+
+- A non-zero `exitCode` from a script does **not** throw — it's a normal
+  result. Check `result.ok` or `result.exitCode`.
+- A successful response with empty `stdout` does **not** throw — the script
+  may have legitimately produced no output.
+- Pre-bootstrap errors (e.g. wrong `authSecret`) come back as `AuthError` with
+  `status === 403`, same shape as a runtime auth failure.
diff --git a/plugins/sql-fs/skills/ts-sdk/ref/models.md b/plugins/sql-fs/skills/ts-sdk/ref/models.md
new file mode 100644
index 0000000..a7f1a04
--- /dev/null
+++ b/plugins/sql-fs/skills/ts-sdk/ref/models.md
@@ -0,0 +1,159 @@
+# Models reference
+
+All models are plain TypeScript `interface`s (parsed from the API's JSON).
+Field names use camelCase, matching the server's response shape directly.
+`ReadResult` is a class (it carries a `text()` helper); everything else is a
+structural type.
+
+```typescript
+import {
+  type SandboxRecord, type SandboxInfo,
+  type ExecResult, type BatchExecResult, type StreamEvent,
+  type TreeEntry, ReadResult, type FileStat,
+  type FileKind, type StreamEventType,
+} from "sql-fs-sdk";
+```
+
+---
+
+## `SandboxRecord` — returned by `sandboxes.create()` and `.list()`
+
+| Field | Type | Notes |
+|---|---|---|
+| `id` | `string` | Sandbox UUID |
+| `name` | `string \| null` | Human label, optional at creation |
+| `owner` | `string` | The `sub` claim of the creating token |
+| `createdAt` | `string` | ISO-8601 UTC |
+| `python` | `boolean` | CPython WASM runtime enabled? |
+| `javascript` | `boolean` | QuickJS runtime enabled? |
+
+```typescript
+const sb = await client.sandboxes.create({ name: "demo", python: true });
+console.log(sb.record?.id, sb.record?.python);
+```
+
+---
+
+## `SandboxInfo` — returned by `sandboxes.get()`
+
+Same identity fields as `SandboxRecord` minus the runtime flags, plus
+`lastUsedAt`.
+
+| Field | Type | Notes |
+|---|---|---|
+| `id` | `string` | |
+| `name` | `string \| null` | |
+| `owner` | `string` | |
+| `createdAt` | `string` | ISO-8601 UTC |
+| `lastUsedAt` | `string` | ISO-8601 UTC; touched by every exec call |
+
+---
+
+## `ExecResult` — returned by `sb.exec()`
+
+The headline result type. Designed for direct property access — no JSON
+parsing required.
+
+| Field / property | Type | Notes |
+|---|---|---|
+| `stdout` | `string` | Captured stdout (UTF-8 decoded server-side) |
+| `stderr` | `string` | Captured stderr |
+| `exitCode` | `number` | 0 = success |
+| `exitSignal` | `string \| null` | Set if the process was terminated by signal |
+| `timedOut` | `boolean` | True if the script hit `timeoutMs` |
+| `durationMs` | `number` | Wall-clock duration of the script |
+| `ok` | `boolean` (readonly) | Convenience: `exitCode === 0` |
+| `error` | `string` (readonly) | **Alias for `stderr`** |
+
+```typescript
+const r = await sb.exec("ls /home/user");
+if (!r.ok) throw new Error(`ls failed (exit ${r.exitCode}): ${r.error}`);
+const files = r.stdout.split("\n").filter(Boolean);
+```
+
+**Note on `r.error`:** it returns the captured stderr text. It does **not**
+indicate transport-level errors — those throw. A 0-exit script with content on
+stderr will still have `r.ok === true` and a non-empty `r.error`.
+
+---
+
+## `BatchExecResult` — one entry in `sb.execBatch()` results
+
+| Field / property | Type | Notes |
+|---|---|---|
+| `id` | `string` | Echo of the input id; lets you correlate scripts to results |
+| `stdout` | `string` | |
+| `stderr` | `string` | |
+| `exitCode` | `number` | `-1` if the batch budget was exhausted before this script ran |
+| `durationMs` | `number` | Wall-clock duration in ms; `0` if the script never ran (budget pre-exhausted or batch aborted) |
+| `error` | `string \| undefined` | Set when the server itself errored on this entry (e.g. `"timeout"`) |
+| `ok` | `boolean` (readonly) | `exitCode === 0` |
+
+```typescript
+const results = await sb.execBatch([...]);
+const byId = new Map(results.map((r) => [r.id, r]));
+if (!byId.get("tree")?.ok) {
+  // ...
+}
+```
+
+---
+
+## `StreamEvent` — yielded by `sb.execStream()`
+
+A tagged union over three SSE event types. Inspect `.type` first.
+
+| Field | Type | Set when |
+|---|---|---|
+| `type` | `"stdout" \| "stderr" \| "exit"` | always |
+| `data` | `string \| undefined` | `type` is `"stdout"` / `"stderr"` — the chunk text |
+| `t` | `number \| undefined` | server-side timestamp (seconds since exec start) |
+| `exitCode` | `number \| undefined` | `type === "exit"` |
+| `durationMs` | `number \| undefined` | `type === "exit"` |
+| `error` | `string \| undefined` | `type === "exit"` if the server short-circuited |
+
+```typescript
+for await (const ev of sb.execStream("...")) {
+  if (ev.type === "stdout") write(ev.data ?? "");
+  else if (ev.type === "stderr") warn(ev.data ?? "");
+  else if (ev.type === "exit") {
+    if (ev.exitCode !== 0) throw new Error(`exec failed in ${ev.durationMs}ms: ${ev.error}`);
+  }
+}
+```
+
+---
+
+## `TreeEntry` — banned for agent use (returned by `sb.fs.tree()`)
+
+Documented for completeness. Agents should use `sb.exec("find ... -printf ...")` instead.
+
+| Field | Type | Notes |
+|---|---|---|
+| `path` | `string` | Absolute path |
+| `kind` | `"file" \| "dir" \| "symlink"` | |
+| `size` | `number` | Bytes; 0 for directories |
+| `mtime` | `string` | ISO-8601 UTC |
+
+---
+
+## `ReadResult` — banned for agent use (returned by `sb.fs.read()`)
+
+A class, not an interface — it carries a `text()` decode helper.
+
+| Member | Type | Notes |
+|---|---|---|
+| `content` | `Uint8Array` | Raw file body |
+| `stat` | `FileStat \| undefined` | Parsed `X-FS-Stat` response header |
+| `text(encoding = "utf-8")` | method → `string` | Decode `content` as text |
+
+---
+
+## `FileStat` — banned for agent use
+
+| Field | Type |
+|---|---|
+| `kind` | `"file" \| "dir" \| "symlink"` |
+| `mode` | `number` |
+| `size` | `number` |
+| `mtime` | `string` |
diff --git a/plugins/sql-fs/skills/ts-sdk/ref/sandbox.md b/plugins/sql-fs/skills/ts-sdk/ref/sandbox.md
new file mode 100644
index 0000000..b923995
--- /dev/null
+++ b/plugins/sql-fs/skills/ts-sdk/ref/sandbox.md
@@ -0,0 +1,292 @@
+# `Sandbox` reference
+
+A handle bound to a single sandbox id. Get one from
+`client.sandboxes.create(...)` (which returns the new sandbox) or
+`client.sandboxes.attach(id)` (which is free, no network call).
+
+```typescript
+import type { Sandbox } from "sql-fs-sdk";  // type only — never construct directly
+```
+
+`Sandbox` is **not** meant to be constructed directly. Always go through
+`client.sandboxes.create()` or `client.sandboxes.attach()`.
+
+---
+
+## ⛔ Method policy
+
+The `sb.fs.*` namespace exists for completeness but is **banned for agent use**.
+Use `sb.exec / execBatch / execStream` instead. The exception is
+`sb.ingestFiles(...)` for one-time bulk bootstrapping. See `SKILL.md` for the
+full translation table.
+
+This file documents the methods you SHOULD use. The banned `fs.*` methods are
+listed at the bottom for completeness and to support legitimate non-agent
+tooling (e.g. uploaders).
+
+---
+
+## `sb.id` / `sb.record`
+
+```typescript
+sb.id          // string — sandbox UUID
+sb.record      // SandboxRecord | undefined — full record at creation; undefined if attached
+```
+
+---
+
+## Exec
+
+### `sb.exec(script, options?): Promise<ExecResult>`
+
+```typescript
+interface ExecOptions {
+  cwd?: string;
+  env?: Record<string, string>;
+  timeoutMs?: number;        // 1 ≤ ms ≤ 300_000 (default 30_000)
+  debug?: boolean;           // true = prepend `set -x` for tracing
+  readOnly?: boolean;        // true = skip exclusive lock; throws on any write
+  retryOn5xx?: boolean;      // opt in to retrying transient 5xx on this write exec
+}
+```
+
+Buffered bash execution. Maps to `POST /v1/sandboxes/{id}/exec-sync`. Resolves
+once the script exits with a flat `ExecResult` carrying
+`stdout / stderr / exitCode / ok / durationMs`.
+
+```typescript
+const result = await sb.exec("echo hello && ls /home/user", {
+  cwd: "/home/user",
+  env: { FOO: "bar" },          // added on top of sandbox-level env
+  timeoutMs: 15_000,
+  readOnly: false,
+});
+console.log(result.stdout);     // string
+console.log(result.error);      // alias for .stderr
+console.log(result.exitCode, result.ok, result.durationMs);
+```
+
+The SDK sets the underlying request timeout to `max(timeoutMs + 5000, 35_000)`,
+so a genuine server-side timeout surfaces as `ExecTimeoutError` (HTTP 408), not
+a client-side network timeout.
+
+**Idempotency:** `exec` is **not** retried unless you pass `readOnly: true` or
+`retryOn5xx: true` (the server cannot safely re-execute an arbitrary write
+script). Wrap your own retry logic if needed.
+
+### `sb.execBatch(scripts, options?): Promise<BatchExecResult[]>`
+
+Maps to `POST /v1/sandboxes/{id}/exec-sync-batch`. Run up to **50 scripts
+sequentially** (or in parallel when `readOnly: true`) in one HTTP round-trip.
+Each entry is `{ id: string, script: string }`.
+
+```typescript
+interface ExecBatchOptions {
+  timeoutMs?: number;            // outer ceiling covering the whole batch (default 30_000)
+  perScriptTimeoutMs?: number;   // each script independently limited
+  readOnly?: boolean;            // parallel execution; throws on any write
+  retryOn5xx?: boolean;
+}
+
+const results = await sb.execBatch(
+  [
+    { id: "tree", script: "find /home/user -type f | head -20" },
+    { id: "imports", script: "grep -rn '^from langgraph' /home/user | head -10" },
+    { id: "count", script: "find /home/user -type f | wc -l" },
+  ],
+  { timeoutMs: 60_000, perScriptTimeoutMs: 5_000, readOnly: true },
+);
+for (const r of results) {
+  console.log(r.id, r.exitCode, r.ok);
+  console.log(r.stdout);
+}
+```
+
+**`perScriptTimeoutMs`** — optional per-script budget (ms). When set, each
+script gets its own independent timeout rather than sharing `timeoutMs`.
+`timeoutMs` still acts as the outer wall-clock ceiling for the whole batch.
+Recommended for capability probes (`python3 -c 'import foo'` × N) where a slow
+first script would otherwise silently exhaust the shared budget and produce false
+negatives for later scripts.
+
+If the shared `timeoutMs` budget is exhausted, remaining results carry
+`exitCode === -1` and `error === "timeout"` — you still get a result row for
+every input id.
+
+**This is the headline performance win over `exec`.** Each individual `exec-sync`
+costs ~700 ms steady-state regardless of script complexity (HTTP round-trip
+dominates). Bundling 20 trivial probes into one `execBatch` runs in ~700 ms
+total, ~35 ms/probe. Always batch independent exploration probes.
+
+### `sb.execStream(script, options?): AsyncGenerator<StreamEvent>`
+
+Maps to `POST /v1/sandboxes/{id}/exec` (Server-Sent Events). Yields
+`StreamEvent` instances of three types until the server emits `exit`:
+
+```typescript
+for await (const ev of sb.execStream("for i in 1 2 3; do echo $i; sleep 1; done")) {
+  if (ev.type === "stdout") process.stdout.write(ev.data ?? "");
+  else if (ev.type === "stderr") process.stderr.write(ev.data ?? "");
+  else if (ev.type === "exit") console.log(`\nexit=${ev.exitCode} duration=${ev.durationMs}ms`);
+}
+```
+
+`ExecStreamOptions` is `ExecOptions` minus `retryOn5xx` (`cwd`, `env`,
+`timeoutMs`, `debug`, `readOnly`).
+
+**Iterator semantics:**
+- The connection is closed automatically when the generator is exhausted (on
+  `exit` event) **or** when you `break` out of the `for await` loop (the
+  generator's `finally` cancels the response body).
+- Don't hold a half-consumed generator open — finish the loop or `break` so the
+  underlying response is released.
+- A server-side `error` SSE event is thrown as a `ValidationError` (status 422)
+  mid-iteration.
+- Streaming endpoints are **not** retried; at-most-once semantics.
+
+**When to prefer `execStream` over `exec`:**
+- The script produces output incrementally and you need to display it live
+  (e.g. a long build log).
+- You need to bail early on a specific output pattern.
+
+For everything else, `exec` (buffered) is simpler and faster — no SSE framing
+overhead per chunk.
+
+---
+
+## Ingest (bootstrap only)
+
+### `sb.ingestFiles(files, options?): Promise<Record<string, unknown>>`
+
+Maps to `POST /v1/sandboxes/{id}/ingest-files`. **Allowed for one-time
+bootstrap of a fresh sandbox** — for any further file mutation, switch to
+`exec` (see SKILL.md policy).
+
+```typescript
+await sb.ingestFiles(
+  {
+    "main.py": "print('hi')\n",
+    "config.json": new TextEncoder().encode('{"k":"v"}'),  // bytes are auto base64'd
+    "subdir/util.py": await readFile("local/util.py"),       // Uint8Array | ArrayBuffer | string
+  },
+  { basePath: "/home/user/project" },
+);
+```
+
+- Keys are paths **relative to `basePath`** (default `/home/user/project`).
+- Values are `FileContent = string | Uint8Array | ArrayBuffer`. Strings are
+  UTF-8 encoded; bytes pass through. The SDK base64-encodes everything before
+  sending.
+- Wire payload is JSON; expect ~33% inflation from base64.
+- One HTTP round-trip regardless of file count.
+
+Returns the server's response object, e.g. `{ status: "ok", fileCount: 125 }`.
+
+**Per-file size check (client-side).** Before encoding anything, each file is
+checked against the client's `maxFileSize` (default 64 MiB — see `ref/client.md`).
+A file over the limit throws `ValidationError` (code `EFILE_TOO_LARGE`) and
+**nothing is sent**. Raise or disable it with `new Client({ maxFileSize })` /
+`maxFileSize: 0`.
+
+**8 MiB `python3` read limit (client-side).** Any file larger than 8 MiB throws
+`ValidationError` (code `EFILE_TOO_LARGE_FOR_CPYTHON`) and **nothing is sent**.
+The `python3` runtime (CPython WASM) reads sandbox files through an 8 MiB IPC
+bridge — `open()` on a larger file fails with an opaque error. The bytes
+themselves ingest fine and stay usable from bash (`cat`/`grep`/`awk`) and
+`js-exec`; only `python3 open()` can't read them. Pass `{ allowOversized: true }`
+to ingest anyway (accepting that `python3` can't read the file), or split the
+file into <8 MiB chunks and recombine them in your script:
+
+```typescript
+// Blocked — a 17 MB CSV the python3 runtime can't open():
+await sb.ingestFiles({ "data.csv": bigCsvBytes });                       // throws EFILE_TOO_LARGE_FOR_CPYTHON
+
+// Option A — store it anyway for bash/js-exec (grep/awk/cut), not python3:
+await sb.ingestFiles({ "data.csv": bigCsvBytes }, { allowOversized: true });
+
+// Option B — split into <8 MiB chunks, recombine in python3 (see SKILL.md):
+await sb.ingestFiles({ "chunk1.csv": part1, "chunk2.csv": part2, "chunk3.csv": part3 });
+```
+
+**Hard limits to keep in mind:**
+- All file bytes are buffered into one HTTP request body. The server caps the
+  whole body (default 256 MB); after ~33% base64 inflation that's ~190 MB of raw
+  bytes per call. Individual large files (tens of MB) ingest fine and store
+  byte-exact — split very large payloads across multiple `ingestFiles` calls.
+
+---
+
+## Lifecycle
+
+### `sb.delete(): Promise<void>`
+
+Maps to `DELETE /v1/sandboxes/{id}`. Destroys the sandbox and queues its blobs
+for GC. Equivalent to `client.sandboxes.delete(sb.id)`.
+
+```typescript
+try {
+  // ... use sb ...
+} finally {
+  await sb.delete();
+}
+```
+
+---
+
+## ⚠️ `sb.fs.*` — banned for agent use
+
+Listed for completeness only. Translate to `exec` per the SKILL.md policy.
+`q()` is a shell-quoting helper (no built-in `shlex` in JS).
+
+| Method | API route | Use this `exec` instead |
+|---|---|---|
+| `sb.fs.read(path): Promise<ReadResult>` | `GET /files/{path}` | `sb.exec("cat " + q(path))` |
+| `sb.fs.readText(path): Promise<string>` | `GET /files/{path}` | `(await sb.exec("cat " + q(path))).stdout` |
+| `sb.fs.write(path, content)` | `PUT /files/{path}` | `sb.exec("cat > " + q(path) + " <<'EOF'\n...\nEOF\n")` |
+| `sb.fs.writeFiles({...})` | `POST /writeFiles` | One `sb.exec(...)` with stacked heredocs, OR `sb.ingestFiles({...})` for bootstrap |
+| `sb.fs.delete(path, { recursive })` | `DELETE /files/{path}` | `sb.exec("rm -rf " + q(path))` |
+| `sb.fs.mkdir(path, { recursive })` | `POST /mkdir` | `sb.exec("mkdir -p " + q(path))` |
+| `sb.fs.tree({ prefix, depth })` | `GET /tree` | `sb.exec("find " + root + " -printf '%y %s %p\\n'")` |
+
+---
+
+## End-to-end example
+
+```typescript
+import { Client } from "sql-fs-sdk";
+
+const client = new Client({
+  baseUrl: process.env.BASE_URL!,
+  authSecret: process.env.AUTH_SECRET!,
+  sub: "explorer",
+});
+try {
+  const sb = await client.sandboxes.create({ name: "explore" });
+  try {
+    // Bootstrap with a manifest of source files (one round-trip).
+    await sb.ingestFiles(
+      { "main.py": "print('hi')\n", "lib/util.py": "def f(): pass\n" },
+      { basePath: "/home/user/proj" },
+    );
+
+    // Explore via execBatch — single round-trip, ~700 ms total for 4 probes.
+    const results = await sb.execBatch(
+      [
+        { id: "tree", script: "find /home/user/proj -type f" },
+        { id: "py_files", script: "find /home/user/proj -name '*.py' | wc -l" },
+        { id: "imports", script: "grep -rhn '^from ' /home/user/proj | head -20" },
+        { id: "main", script: "cat /home/user/proj/main.py" },
+      ],
+      { timeoutMs: 30_000, readOnly: true },
+    );
+    for (const r of results) {
+      console.log(`[${r.id}] exit=${r.exitCode}`);
+      console.log(r.stdout);
+    }
+  } finally {
+    await sb.delete();
+  }
+} finally {
+  client.close();
+}
+```