zilmate 1.8.1 → 1.9.1

package/.agents/skills/tavily-research/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: tavily-research
+description: |
+  Conduct comprehensive AI-powered research with citations via the Tavily CLI. Use this skill when the user wants deep research, a detailed report, a comparison, market analysis, literature review, or says "research", "investigate", "analyze in depth", "compare X vs Y", "what does the market look like for", or needs multi-source synthesis with explicit citations. Returns a structured report grounded in web sources. Takes 30-120 seconds. For quick fact-finding, use tavily-search instead.
+allowed-tools: Bash(tvly *)
+---
+
+# tavily research
+
+AI-powered deep research that gathers sources, analyzes them, and produces a cited report. Takes 30-120 seconds.
+
+## Before running any command
+
+If `tvly` is not found on PATH, install it first:
+
+```bash
+curl -fsSL https://cli.tavily.com/install.sh | bash && tvly login
+```
+
+Do not skip this step or fall back to other tools.
+
+See [tavily-cli](../tavily-cli/SKILL.md) for alternative install methods and auth options.
+
+## When to use
+
+- You need comprehensive, multi-source analysis
+- The user wants a comparison, market report, or literature review
+- Quick searches aren't enough — you need synthesis with citations
+- Step 5 in the [workflow](../tavily-cli/SKILL.md): search → extract → map → crawl → **research**
+
+## Quick start
+
+```bash
+# Basic research (waits for completion)
+tvly research "competitive landscape of AI code assistants"
+
+# Pro model for comprehensive analysis
+tvly research "electric vehicle market analysis" --model pro
+
+# Stream results in real-time
+tvly research "AI agent frameworks comparison" --stream
+
+# Save report to file
+tvly research "fintech trends 2025" --model pro -o fintech-report.md
+
+# JSON output for agents
+tvly research "quantum computing breakthroughs" --json
+```
+
+## Options
+
+| Option | Description |
+|--------|-------------|
+| `--model` | `mini`, `pro`, or `auto` (default) |
+| `--stream` | Stream results in real-time |
+| `--no-wait` | Return request_id immediately (async) |
+| `--output-schema` | Path to JSON schema for structured output |
+| `--citation-format` | `numbered`, `mla`, `apa`, `chicago` |
+| `--poll-interval` | Seconds between checks (default: 10) |
+| `--timeout` | Max wait seconds (default: 600) |
+| `-o, --output` | Save output to file |
+| `--json` | Structured JSON output |
+
+## Model selection
+
+| Model | Use for | Speed |
+|-------|---------|-------|
+| `mini` | Single-topic, targeted research | ~30s |
+| `pro` | Comprehensive multi-angle analysis | ~60-120s |
+| `auto` | API chooses based on complexity | Varies |
+
+**Rule of thumb:** "What does X do?" → mini. "X vs Y vs Z" or "best way to..." → pro.
+
+## Async workflow
+
+For long-running research, you can start and poll separately:
+
+```bash
+# Start without waiting
+tvly research "topic" --no-wait --json    # returns request_id
+
+# Check status
+tvly research status <request_id> --json
+
+# Wait for completion
+tvly research poll <request_id> --json -o result.json
+```
+
+## Tips
+
+- **Research takes 30-120 seconds** — use `--stream` to see progress in real-time.
+- **Use `--model pro`** for complex comparisons or multi-faceted topics.
+- **Use `--output-schema`** to get structured JSON output matching a custom schema.
+- **For quick facts**, use `tvly search` instead — research is for deep synthesis.
+- Read from stdin: `echo "query" | tvly research - --json`
+
+## See also
+
+- [tavily-search](../tavily-search/SKILL.md) — quick web search for simple lookups
+- [tavily-crawl](../tavily-crawl/SKILL.md) — bulk extract from a site for your own analysis

package/.agents/skills/upstash/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: upstash
+description: Work with any Upstash TypeScript/JavaScript SDK including Redis, Box, QStash, Workflow, Vector, Search and Ratelimit. Use when the user is working with any Upstash product or SDK.
+---
+
+# Upstash Skills
+
+This skill combines documentation for all Upstash SDKs. Pick the relevant sub-skill below.
+
+## [upstash-box-js](upstash-box-js/overview.md)
+
+Work with the @upstash/box TypeScript/JavaScript SDK for sandboxed cloud containers with AI agents, shell, filesystem, and git. Use when building with Upstash Box, creating sandboxed environments, running AI agents in containers, or orchestrating parallel boxes.
+
+## [upstash-box-py](upstash-box-py/overview.md)
+
+Work with the upstash-box Python SDK for sandboxed cloud containers with AI agents, shell, filesystem, and git. Use when building with Upstash Box in Python, creating sandboxed environments, running AI agents in containers, or orchestrating parallel boxes.
+
+## [upstash-cli](upstash-cli/overview.md)
+
+Run the Upstash CLI (`upstash`) against the Upstash Developer API for Redis, Vector, Search, QStash, and teams. Use when listing or managing databases, backups, vector/search indexes, QStash instances, team members, stats, or any non-interactive Upstash automation with JSON output and terminal commands.
+
+## [upstash-qstash-js](upstash-qstash-js/overview.md)
+
+Work with the QStash TypeScript/JavaScript SDK for serverless messaging, scheduling. Use when publishing messages to HTTP endpoints, creating schedules, managing queues, verifying incoming messages and other QStash features in serverless environments.
+
+## [upstash-ratelimit-js](upstash-ratelimit-js/overview.md)
+
+Lightweight guidance for using the Upstash Redis RateLimit TypeScript/JavaScript SDK, including setup steps, basic usage, and pointers to advanced algorithm, features, pricing, and traffic‑protection docs.
+
+## [upstash-redis-js](upstash-redis-js/overview.md)
+
+Work with the Upstash Redis TypeScript/JavaScript SDK for serverless Redis operations. Use for caching, session storage, rate limiting, leaderboards, full-text search (querying, filtering, aggregating) with Upstash Redis Search (different from regular FT.SEARCH), and all Redis data structures. Supports automatic serialization/deserialization of JavaScript types. Upstash Redis Search also available via @upstash/search-redis and @upstash/search-ioredis adapters for TCP clients.
+
+## [upstash-redis-start](upstash-redis-start/overview.md)
+
+Provision a zero-config, no-signup Upstash Redis database for an AI agent via a single POST to `https://upstash.com/start-redis`. Use when an agent needs scratch Redis for short-term memory, conversation history, sub-agent work queues, or ranked recall and the user has not provided credentials. The database lives 3 days unless the user claims it.
+
+## [upstash-search-js](upstash-search-js/overview.md)
+
+Skills covering Upstash Search quick starts, core concepts, and TypeScript/JavaScript SDK usage. Use when a user asks how to get started, how indexing works, or how to use the TS client.
+
+## [upstash-vector-js](upstash-vector-js/overview.md)
+
+Skills for Upstash Vector features, TypeScript/JavaScript SDK usage, and integrations. Use when users ask how to work with Vector, its TS SDK, features, or supported frameworks.
+
+## [upstash-workflow-js](upstash-workflow-js/overview.md)
+
+Skills for the Upstash Workflow TypeScript/JavaScript SDK to define, trigger, and manage workflows. Use this Skill whenever a user wants to create workflow endpoints, run steps, or interact with the Upstash Workflow client.

package/.agents/skills/upstash/upstash-box-js/overview.md

@@ -0,0 +1,243 @@
+# @upstash/box SDK
+
+Sandboxed cloud containers with built-in AI agents, shell, filesystem, and git.
+
+## Install & Setup
+
+```bash
+npm install @upstash/box
+```
+
+Set `UPSTASH_BOX_API_KEY` env var or pass `apiKey` to constructors.
+
+## Box Lifecycle
+
+```ts
+import { Box, Agent, ClaudeCode, BoxApiKey } from "@upstash/box"
+
+// Create with agent + git + env vars
+const box = await Box.create({
+  runtime: "node", // "node" | "python" | "golang" | "ruby" | "rust"
+  agent: {
+    harness: Agent.ClaudeCode, // Agent.Codex | Agent.OpenCode
+    model: ClaudeCode.Sonnet_4_5,
+    // apiKey options:
+    //   omit          → server decides which key to use
+    //   BoxApiKey.UpstashKey  → use Upstash-provided LLM key
+    //   BoxApiKey.StoredKey   → use key previously stored via Upstash Console
+    //   "sk-..."      → direct API key string
+    apiKey: BoxApiKey.UpstashKey,
+  },
+  git: { // all fields optional
+    token: process.env.GITHUB_TOKEN, // alternatively link your GitHub account via Upstash Console
+    userName: "Bot",
+    userEmail: "bot@example.com",
+  },
+  env: { DATABASE_URL: "..." },
+  skills: ["upstash/qstash-js"], // GitHub repos as agent skills
+})
+
+// Reconnect, list, delete, pause/resume
+const same = await Box.get(box.id)
+const all = await Box.list()
+await box.pause()
+await box.resume()
+await box.delete()  // irreversible
+const { status } = await box.getStatus()
+```
+
+## Agent Runs
+
+```ts
+import { z } from "zod"
+
+// Structured output with Zod schema
+const run = await box.agent.run({
+  prompt: "Review the code for security issues",
+  responseSchema: z.object({
+    verdict: z.enum(["approved", "changes_requested"]),
+    findings: z.array(z.object({
+      severity: z.enum(["high", "medium", "low"]),
+      file: z.string(),
+      issue: z.string(),
+    })),
+  }),
+  timeout: 120_000,
+  maxRetries: 2,
+  onToolUse: (tool) => console.log(tool.name, tool.input),
+})
+
+run.status  // "running" | "completed" | "failed" | "cancelled" | "detached"
+run.result  // typed from schema
+run.cost    // { inputTokens, outputTokens, computeMs, totalUsd }
+
+// Streaming
+const stream = await box.agent.stream({
+  prompt: "Build a REST API",
+})
+for await (const chunk of stream) { console.log(chunk) }
+
+// Fire-and-forget with webhook
+await box.agent.run({
+  prompt: "Run tests",
+  webhook: { url: "https://example.com/hook", headers: { Authorization: "Bearer ..." } },
+})
+```
+
+## Run Fields
+
+Every `run` (agent, command, or code) returns a `Run<T>`:
+
+```ts
+const run = await box.exec.command("npm test")
+run.id        // run ID
+run.status    // "completed" | "failed" | ...
+run.result    // string output (or typed T with responseSchema)
+run.exitCode  // number | null (null for agent runs)
+run.cost      // { inputTokens, outputTokens, computeMs, totalUsd }
+
+await run.cancel()          // cancel a running run
+const logs = await run.logs() // [{ timestamp, level, message }]
+```
+
+## Shell Execution
+
+```ts
+// Run commands
+const run = await box.exec.command("echo hello && ls -la")
+
+// Run code snippets — lang: "js" | "ts" | "python"
+const run2 = await box.exec.code({ code: "console.log(1+1)", lang: "js", timeout: 10_000 })
+
+// Streaming shell
+const stream = await box.exec.stream("npm run build")
+for await (const chunk of stream) {
+  // chunk: { type: "output", data } | { type: "exit", exitCode, cpuNs }
+}
+```
+
+## Filesystem
+
+```ts
+await box.files.write({ path: "/workspace/home/app.js", content: "console.log('hi')" })
+const content = await box.files.read("/workspace/home/app.js")
+const entries = await box.files.list("/workspace/home") // [{ name, path, size, is_dir, mod_time }]
+
+// Binary files — use encoding: "base64" for read and write
+await box.files.write({ path: "/workspace/home/image.png", content: base64String, encoding: "base64" })
+const b64 = await box.files.read("/workspace/home/image.png", { encoding: "base64" })
+
+// Upload local files, download box files
+await box.files.upload([{ path: "./local/file.txt", destination: "/workspace/home/file.txt" }])
+await box.files.download({ folder: "./output" })
+```
+
+## cd / Working Directory
+
+The SDK tracks `cwd` client-side. All operations (exec, files, git, agent) run relative to it.
+
+```ts
+box.cwd // current working directory (starts at /workspace/home)
+await box.cd("my-repo")     // relative to current cwd
+await box.cd("/workspace/home/other") // absolute path
+```
+
+## Git
+
+```ts
+await box.git.clone({ repo: "github.com/org/repo", branch: "main" })
+await box.cd("repo") // cd into cloned repo
+
+const status = await box.git.status()
+const diff = await box.git.diff()
+const { sha } = await box.git.commit({ message: "fix: resolve bug" })
+await box.git.push({ branch: "feature/fix" })
+
+await box.git.checkout({ branch: "release/v2" })
+const pr = await box.git.createPR({ title: "Fix bug", body: "...", base: "main" })
+// pr: { url, number, title, base }
+
+// Arbitrary git commands
+const { output } = await box.git.exec({ args: ["log", "--oneline", "-5"] })
+```
+
+## Snapshots & Fork
+
+```ts
+// Snapshot — checkpoint workspace state
+const snap = await box.snapshot({ name: "after-setup" })
+// snap: { id, name, box_id, size_bytes, status, created_at }
+
+const restored = await Box.fromSnapshot(snap.id)
+const snaps = await box.listSnapshots()
+await box.deleteSnapshot(snap.id)
+
+// Fork — clone live state into a new box
+const forked = await box.fork()
+```
+
+## EphemeralBox
+
+Lightweight, short-lived boxes (max 3 days). No agent, git, snapshot, or fork. Supports exec, files, cd, and snapshots only.
+
+```ts
+import { EphemeralBox } from "@upstash/box"
+
+const ebox = await EphemeralBox.create({
+  runtime: "python",
+  ttl: 3600,  // seconds, max 259200 (3 days)
+  env: { API_KEY: "..." },
+})
+
+ebox.expiresAt // unix timestamp when auto-deleted
+await ebox.exec.command("python -c 'print(1+1)'")
+await ebox.exec.code({ code: "print('hi')", lang: "python" })
+await ebox.files.write({ path: "/workspace/home/data.json", content: "{}" })
+await ebox.cd("subdir")
+await ebox.delete()
+
+// Restore from snapshot
+const ebox2 = await EphemeralBox.fromSnapshot(snap.id, { ttl: 7200 })
+```
+
+## Public URLs
+
+Expose box ports as public URLs with optional auth.
+
+```ts
+const publicURL = await box.getPublicURL(3000)
+// publicURL: { url: "https://{id}-3000.preview.box.upstash.com", port }
+
+const authed = await box.getPublicURL(3000, { bearerToken: true })
+// authed: { url, port, token }
+
+const basic = await box.getPublicURL(3000, { basicAuth: true })
+// basic: { url, port, username, password }
+
+const { publicURLs } = await box.listPublicURLs()
+await box.deletePublicURL(3000)
+```
+
+## MCP Servers
+
+Attach MCP servers to the box agent.
+
+```ts
+const box = await Box.create({
+  agent: { harness: Agent.ClaudeCode, model: ClaudeCode.Sonnet_4_5 },
+  mcpServers: [
+    { name: "fs", package: "@modelcontextprotocol/server-filesystem" },
+    { name: "custom", url: "https://mcp.example.com/sse", headers: { Authorization: "..." } },
+  ],
+})
+```
+
+## Gotchas
+
+- Default working directory is `/workspace/home`, not `/home` or `/`
+- `box.cd()` is client-side tracking — it validates the path exists but doesn't change the box's shell cwd. All SDK methods use it automatically.
+- `EphemeralBox` does NOT support `agent`, `git`, `fork`, or public URLs — use full `Box` for those
+- `run.exitCode` is `null` for agent runs, only available for exec commands
+- `box.delete()` is irreversible — snapshot first if you need the state
+- Git operations require `git.token` in `BoxConfig` for private repos and PRs
+- `Box.fromSnapshot()` creates a new box — it does not modify the original

package/.agents/skills/upstash/upstash-box-py/overview.md

@@ -0,0 +1,275 @@
+# upstash-box Python SDK
+
+Sandboxed cloud containers with built-in AI agents, shell, filesystem, and git.
+
+## Install & Setup
+
+```bash
+pip install upstash-box
+```
+
+Set `UPSTASH_BOX_API_KEY` env var or pass `api_key` to constructors.
+
+The SDK ships both a synchronous `Box` (used in the examples below) and an
+asynchronous `AsyncBox` (`box = await AsyncBox.create(...)`, `await box.agent.run(...)`).
+The async surface is identical with `await` and `async for`.
+
+## Box Lifecycle
+
+```python
+import os
+from upstash_box import Box, Agent, ClaudeCode, BoxApiKey
+
+# Create with agent + git + env vars
+box = Box.create(
+    runtime="node",  # "node" | "python" | "golang" | "ruby" | "rust"
+    agent={
+        "harness": Agent.CLAUDE_CODE,  # Agent.CODEX | Agent.OPEN_CODE
+        "model": ClaudeCode.SONNET_4_5,  # or a plain string "anthropic/claude-sonnet-4-5"
+        # api_key options:
+        #   omit                    → server decides which key to use
+        #   BoxApiKey.UPSTASH_KEY   → use Upstash-provided LLM key
+        #   BoxApiKey.STORED_KEY    → use key previously stored via Upstash Console
+        #   "sk-..."                → direct API key string
+        "api_key": BoxApiKey.UPSTASH_KEY,
+    },
+    git={  # all fields optional
+        "token": os.environ["GITHUB_TOKEN"],  # or link your GitHub account via Upstash Console
+        "user_name": "Bot",
+        "user_email": "bot@example.com",
+    },
+    env={"DATABASE_URL": "..."},
+    skills=["upstash/qstash-js"],  # GitHub repos as agent skills
+)
+
+# Reconnect, list, delete, pause/resume
+same = Box.get(box.id)
+all_boxes = Box.list()
+box.pause()
+box.resume()
+box.delete()  # irreversible
+status = box.get_status()["status"]
+```
+
+## Agent Runs
+
+```python
+from pydantic import BaseModel
+
+# Structured output with a Pydantic model (or a raw JSON-schema dict)
+class Finding(BaseModel):
+    severity: str  # "high" | "medium" | "low"
+    file: str
+    issue: str
+
+class Review(BaseModel):
+    verdict: str  # "approved" | "changes_requested"
+    findings: list[Finding]
+
+run = box.agent.run(
+    prompt="Review the code for security issues",
+    response_schema=Review,
+    timeout=120_000,
+    max_retries=2,
+    on_tool_use=lambda tool: print(tool["name"], tool["input"]),
+)
+
+run.status   # "running" | "completed" | "failed" | "cancelled" | "detached"
+run.result   # typed from schema (a Review instance)
+run.cost     # RunCost(input_tokens, output_tokens, compute_ms, total_usd)
+
+# Streaming
+stream = box.agent.stream(prompt="Build a REST API")
+for chunk in stream:
+    print(chunk)
+
+# Fire-and-forget with webhook
+box.agent.run(
+    prompt="Run tests",
+    webhook={"url": "https://example.com/hook", "headers": {"Authorization": "Bearer ..."}},
+)
+```
+
+## Run Fields
+
+Every `run` (agent, command, or code) returns a `Run`:
+
+```python
+run = box.exec.command("npm test")
+run.id         # run ID
+run.status     # "completed" | "failed" | ...
+run.result     # string output (or typed result with response_schema)
+run.exit_code  # int | None (None for agent runs)
+run.cost       # RunCost(input_tokens, output_tokens, compute_ms, total_usd)
+
+run.cancel()          # cancel a running run
+logs = run.logs()     # [RunLog(timestamp, level, message)]
+```
+
+## Shell Execution
+
+```python
+# Run commands
+run = box.exec.command("echo hello && ls -la")
+
+# Run code snippets — lang: "js" | "ts" | "python"
+run2 = box.exec.code(code="print(1 + 1)", lang="python", timeout=10_000)
+
+# Streaming shell
+stream = box.exec.stream("npm run build")
+for chunk in stream:
+    # chunk: ExecOutputChunk(type="output", data) | ExecExitChunk(type="exit", exit_code, cpu_ns)
+    ...
+```
+
+## Filesystem
+
+```python
+box.files.write(path="/workspace/home/app.py", content="print('hi')")
+content = box.files.read("/workspace/home/app.py")
+entries = box.files.list("/workspace/home")  # [FileEntry(name, path, size, is_dir, mod_time)]
+
+# Binary files — use encoding="base64" for read and write
+box.files.write(path="/workspace/home/image.png", content=base64_string, encoding="base64")
+b64 = box.files.read("/workspace/home/image.png", encoding="base64")
+
+# Upload local files, download box files
+box.files.upload([{"path": "./local/file.txt", "destination": "/workspace/home/file.txt"}])
+box.files.download(folder="./output")
+```
+
+## cd / Working Directory
+
+The SDK tracks `cwd` client-side. All operations (exec, files, git, agent) run relative to it.
+
+```python
+box.cwd  # current working directory (starts at /workspace/home)
+box.cd("my-repo")                  # relative to current cwd
+box.cd("/workspace/home/other")    # absolute path
+```
+
+## Git
+
+```python
+box.git.clone(repo="github.com/org/repo", branch="main")
+box.cd("repo")  # cd into cloned repo
+
+status = box.git.status()
+diff = box.git.diff()
+result = box.git.commit(message="fix: resolve bug")  # GitCommitResult(sha, message)
+box.git.push(branch="feature/fix")
+
+box.git.checkout(branch="release/v2")
+pr = box.git.create_pr(title="Fix bug", body="...", base="main")
+# pr: PullRequest(url, number, title, base)
+
+# Arbitrary git commands
+output = box.git.exec(args=["log", "--oneline", "-5"])
+```
+
+## Snapshots
+
+```python
+# Snapshot — checkpoint workspace state
+snap = box.snapshot(name="after-setup")
+# snap: Snapshot(id, name, box_id, size_bytes, status, created_at)
+
+restored = Box.from_snapshot(snap.id)
+snaps = box.list_snapshots()
+box.delete_snapshot(snap.id)
+```
+
+## EphemeralBox
+
+Lightweight, short-lived boxes (max 3 days). No agent or git. Supports exec, files,
+schedule, cd, network policy, and snapshots only.
+
+```python
+from upstash_box import EphemeralBox
+
+ebox = EphemeralBox.create(
+    runtime="python",
+    ttl=3600,  # seconds, max 259200 (3 days)
+    env={"API_KEY": "..."},
+)
+
+ebox.expires_at  # unix timestamp when auto-deleted
+ebox.exec.command("python -c 'print(1+1)'")
+ebox.exec.code(code="print('hi')", lang="python")
+ebox.files.write(path="/workspace/home/data.json", content="{}")
+ebox.cd("subdir")
+ebox.delete()
+
+# Restore from snapshot
+ebox2 = EphemeralBox.from_snapshot(snap.id, ttl=7200)
+```
+
+## Public URLs
+
+Expose box ports as public URLs with optional auth.
+
+```python
+public_url = box.get_public_url(3000)
+# public_url: PublicURL(url="https://{id}-3000.preview.box.upstash.com", port)
+
+authed = box.get_public_url(3000, bearer_token=True)
+# authed: PublicURL(url, port, token)
+
+basic = box.get_public_url(3000, basic_auth=True)
+# basic: PublicURL(url, port, username, password)
+
+result = box.list_public_urls()  # {"public_urls": [PublicURL, ...]}
+box.delete_public_url(3000)
+```
+
+## MCP Servers
+
+Attach MCP servers to the box agent.
+
+```python
+box = Box.create(
+    agent={"harness": Agent.CLAUDE_CODE, "model": ClaudeCode.SONNET_4_5},
+    mcp_servers=[
+        {"name": "fs", "package": "@modelcontextprotocol/server-filesystem"},
+        {"name": "custom", "url": "https://mcp.example.com/sse", "headers": {"Authorization": "..."}},
+    ],
+)
+```
+
+## Async client
+
+The async client mirrors the sync API exactly — `await` the calls and use `async for` to stream.
+
+```python
+import asyncio
+from upstash_box import AsyncBox, Agent
+
+async def main():
+    box = await AsyncBox.create(runtime="node", agent={"harness": Agent.CLAUDE_CODE})
+    run = await box.agent.run(prompt="Set up a Next.js project")
+    print(run.result)
+
+    stream = await box.agent.stream(prompt="Build a REST API")
+    async for chunk in stream:
+        print(chunk)
+
+    await box.delete()
+
+asyncio.run(main())
+```
+
+`asyncio.gather` over many `AsyncBox.create(...)` / `box.agent.run(...)` calls runs boxes in parallel.
+
+## Gotchas
+
+- Public API option keys are **snake_case** in Python: `api_key`, `user_name`, `network_policy`, `response_schema`, `max_retries`, `on_tool_use`, and agent `options` like `max_turns`, `max_budget_usd`.
+- Agent config takes **`harness`** (not the deprecated `provider`/`runner`) — `harness` is required.
+- `response_schema` accepts a Pydantic `BaseModel` subclass (returns a typed instance) or a raw JSON-schema `dict` (returns a `dict`).
+- Default working directory is `/workspace/home`, not `/home` or `/`.
+- `box.cd()` is client-side tracking — it validates the path exists but doesn't change the box's shell cwd. All SDK methods use it automatically.
+- `EphemeralBox` does NOT support `agent` or `git` — use full `Box` for those.
+- `run.exit_code` is `None` for agent runs, only available for exec commands.
+- `box.delete()` is irreversible — snapshot first if you need the state.
+- Git operations require `git.token` in the box config for private repos and PRs.
+- `Box.from_snapshot()` creates a new box — it does not modify the original.
+- Close the transport when done: `box.delete()` closes it, or use `with box:` / `box.close()` (`async with` / `await box.aclose()` for `AsyncBox`).