Docs for AI tools

## Cubicle

This project runs commands in Cubicle Boxes (QEMU/KVM virtual machines) with `@cubicle/sdk`.
Docs for agents: https://docs.cubicle.sh/llms.txt

- Credentials come from the environment: `CB_SDK_API_URL` (https://api.cubicle.sh) and
  `CB_SDK_API_KEY` (a service account API key, `cbk_…`). `new Cubicle()` reads both. Never print,
  log or commit the key, and never use it in browser code.
- `@cubicle/sdk` is ESM-only and needs Node.js 22 or later.
- Create a Box, use it and always delete it:

```ts
import { Cubicle } from "@cubicle/sdk"

const cubicle = new Cubicle()
const box = await cubicle.boxes.create() // a generated name; resolves when the Box is ready
try {
  const result = await box.exec(["sh", "-c", "uname -a && df -h /"])
  if (result.exitCode !== 0) throw new Error(result.stderr)
  console.log(result.stdout)
} finally {
  await box.delete() // resolves when the Box is gone
}
```

- `exec` takes an argv array and runs it without a shell. Wrap pipes, `&&`, globs and redirects in
  `["sh", "-c", "…"]`.
- `exec` has no stdin, no TTY and no streaming. It resolves with
  `{ exitCode, stdout, stderr, timedOut, truncated, operationId }` when the command ends. A non-zero `exitCode`
  is a result, not an exception.
- `timeoutMs` defaults to 60 s and is capped at 10 min. Output defaults to 64 KiB, at most 1 MiB,
  for stdout and stderr together. Check `timedOut` and `truncated`.
- SDK calls wait for you: `create` and `start` until the Box is ready, `stop` and `hibernate` until
  the state is reached, `delete` until the Box is gone (up to 5 min each by default) and `exec`
  until the command ends. Do not add sleeps or polling loops.
- A Box hibernates 60 minutes after it starts, whatever it is doing. Use
  `box.exec(argv, { wake: true })` when a Box may be stopped or hibernated.
- Delete every Box you create, in `finally`. Stopped and hibernated Boxes still hold their CPU,
  memory and disk.
- Commands run as the service account's guest account, which is locked, so do not rely on `sudo`
  or `apt-get install`. When the job needs system packages, create its Box from a snapshot of a
  Box where a person installed them; the service account needs a grant on that Box or the admin
  role.
- Code with an API key cannot connect to a service running in a Box: API keys cannot SSH or join
  the private network, and Boxes have no public ports. Run the client inside the Box with exec,
  against `localhost`.
- Not available: file upload or download, port forwarding, public URLs, streaming output and stdin.