@chusky/sdk 1.6.4 → 1.7.1

package/README.md

@@ -2,477 +2,381 @@
 
 The official TypeScript client for the Chusky Developer API.
 
-Chusky gives applications a persistent, tool-using agent that can stream
-responses, run durable work, use connected business applications, pause for
-human approval, produce artifacts, and continue after restarts. The SDK is the
-server-side boundary for those capabilities; it does not expose Redis,
-Composio credentials, or Chusky's internal `CHUCK_*` tool implementations.
+Use Chusky when your application needs an agent that can reason over context,
+use connected business tools, stream progress, pause for a human decision, and
+continue durable work after a request or process ends.
+
+The SDK is designed for trusted server applications. It keeps connected-app
+credentials out of browsers and mobile clients.
 
 ## Install
 
-```bash
+~~~bash
 npm install @chusky/sdk
-```
+~~~
 
-Requirements: Node.js 18 or newer.
+Node.js 18 or newer is required.
 
-## Five-minute quickstart
+## Quickstart
 
-Create a project-scoped API key in the Chusky dashboard under **Developer API**
-or provision one from a trusted operator environment. Then keep it on your
-server:
+Create an API key in the Chusky dashboard, then configure it in your server
+environment:
 
-```env
+~~~env
 CHUSKY_API_KEY=chsk_your_project_key
-CHUSKY_BASE_URL=https://api.chusky.ai
-```
+~~~
 
-Never put `CHUSKY_API_KEY` in browser JavaScript, a mobile binary, a public
-repository, or client-side environment variables.
+The SDK automatically uses the hosted Chusky API, so `baseUrl` is optional.
+Pass `baseUrl` only when targeting a staging or self-hosted API. Never expose
+`CHUSKY_API_KEY` in browser code, mobile apps, public repositories, or prompts.
 
-```ts
+~~~ts
 import { Chusky } from "@chusky/sdk";
 
 const chusky = new Chusky({
   apiKey: process.env.CHUSKY_API_KEY!,
-  baseUrl: process.env.CHUSKY_BASE_URL,
-  // Use your application's stable user or tenant identity. Do not use a
-  // secret, email address, or the root operator identity here.
+  // Stable ID owned by your application. Do not use a secret.
   userId: "customer_123",
 });
 
 const { thread, run } = await chusky.runs.create(
-  { input: "Prepare a concise renewal brief.", wait: false },
-  { idempotencyKey: "renewal-brief-customer-123-2026-09-21" },
+  {
+    input: "Prepare a concise renewal brief from the available account context.",
+    wait: false,
+    budget: { duration: "5m", maxToolCalls: 20, maxCost: 1 },
+  },
+  { idempotencyKey: "renewal-brief-customer-123-v1" },
 );
 
 const completed = await chusky.runs.wait(thread.id, run.id, {
   timeoutMs: 120_000,
 });
 
-console.log(completed.status);
-console.log(completed.output ?? "The run did not produce text output.");
-
-// Generated image bytes are kept in the owner's private image store. Runs
-// include metadata only; refresh a short-lived download URL when needed.
-for (const image of completed.images ?? []) {
-  const download = await chusky.images.get(image.id);
-  console.log(download.contentType, download.downloadUrl, download.expiresAt);
+if (completed.status === "failed") {
+  throw new Error(completed.error?.message ?? "Chusky run failed.");
 }
-```
-
-Project-scoped API keys need the `images:read` scope to call `images.get()`.
-Treat its signed URL as a temporary secret and do not persist or publicly log it.
-
-For a reliability operation, `chusky.tools.list({ source: "native" })` and
-`chusky.tools.get(slug)` return the native JSON input schema. The SDK helper
-starts one durable run restricted to the selected operation; it does not call
-the native dispatcher outside the normal owner policy and approval path:
-
-```ts
-const { thread, run } = await chusky.tools.run({
-  tool: "CHUCK_ARTIFACT_QA",
-  arguments: { path: "artifacts/quarterly-report.pdf", type: "pdf" },
-}, { idempotencyKey: "qa-quarterly-report-v1" });
-const result = await chusky.runs.wait(thread.id, run.id);
-```
-
-The same helper supports `CHUCK_TOOL_PREFLIGHT`, `CHUCK_INTEGRATION_HEALTH`,
-`CHUCK_FILE_BRIDGE`, `CHUCK_MEDIA_BRIDGE`, and `CHUCK_TOOL_RECOVERY`. For image
-transfer, upload first and pass the returned owner-scoped file ID; only verified
-JPEG, PNG, or WebP images are accepted. Both bridges keep their normal approval
-gates, and approval decisions still belong to the human-facing workflow.
-
-```ts
-const image = await chusky.files.upload({ name: "launch.png", contentType: "image/png", data: imageBytes });
-const { thread, run } = await chusky.tools.run({
-  tool: "CHUCK_MEDIA_BRIDGE",
-  arguments: { source: "current", toolSlug: "SOCIAL_POST", arguments: { caption: "Launch" } },
-  attachments: [image.id],
-});
-```
-
-`userId` is an application-owned identity boundary. Chusky uses it to isolate
-threads, runs, memories, approvals, files, tasks, reminders, connected
-accounts, and durable work. Use the same stable value whenever that user
-returns.
-
-## Examples
-
-The [`examples/`](examples/) directory contains complete TypeScript examples
-that can be adapted directly into a server application:
-
-| Example | Shows |
-| --- | --- |
-| [`quickstart.ts`](examples/quickstart.ts) | Create a durable run and wait for completion |
-| [`streaming.ts`](examples/streaming.ts) | Stream response deltas and handle approval events |
-| [`company-agent.ts`](examples/company-agent.ts) | Use an agent template, policy, budget, and idempotency |
-| [`mission.ts`](examples/mission.ts) | Run multi-step work with proof, evidence, and verification |
-| [`approvals.ts`](examples/approvals.ts) | Present and decide a pending human approval |
-| [`context-and-departments.ts`](examples/context-and-departments.ts) | Save shared context and create a typed department handoff |
-| [`files.ts`](examples/files.ts) | Upload bytes through a short-lived storage intent |
-| [`webhooks.ts`](examples/webhooks.ts) | Register a delivery endpoint and inspect deliveries |
-
-Run an example from the SDK repository with `tsx`:
-
-```bash
-CHUSKY_API_KEY=chsk_... npx tsx examples/quickstart.ts
-```
-
-PowerShell:
 
-```powershell
-$env:CHUSKY_API_KEY = "chsk_..."
-npx tsx examples/quickstart.ts
-```
-
-Examples make real API requests. Use a development project key and a test
-identity when trying them.
+console.log(completed.output ?? "The run completed without text output.");
+~~~
 
 ## The execution model
 
-```text
+~~~text
 Your server
     ↓
 @chusky/sdk
     ↓  authenticated /v1 API
 Chusky runtime
     ↓
-agent loop → native tools / Composio / durable workflows
+agent loop → native tools / connected apps / durable work
     ↓
-business result, artifact, webhook, or approval
-```
+text, approval, artifact, webhook, or verified business result
+~~~
 
-There are three useful execution modes:
+Choose the execution style that matches the job:
 
-1. **Synchronous** — set `wait: true` when the result should return in the
-   request lifecycle and the work is short.
-2. **Durable** — set `wait: false` to receive a task-backed run immediately,
-   then use `runs.get()`, `runs.wait()`, `runs.events()`, `tasks.get()`, or a
-   webhook to observe it.
-3. **Streaming** — use `threads.runs(threadId).stream()` for incremental text
-   and approval events. Streaming is a delivery channel, not the source of
-   truth; persisted run state remains available through `get()` and `events()`.
+| Use case | SDK entry point |
+| --- | --- |
+| One bounded request | <code>chusky.runs.create()</code> and <code>chusky.runs.wait()</code> |
+| Conversation with incremental output | <code>chusky.threads.create()</code> and <code>chusky.threads.runs(threadId).stream()</code> |
+| Work that may pause or retry | <code>runs.get()</code>, <code>runs.events()</code>, <code>runs.resume()</code>, and <code>tasks</code> |
+| Multi-step process with checkpoints and proof | <code>chusky.missions</code> |
+| Delegated agent-to-agent work | <code>chusky.a2a</code> |
+| Recurring or scheduled work | <code>chusky.reminders</code> and <code>chusky.jobs</code> |
 
-### Agent-to-agent tasks
+Persist the returned threadId, runId, taskId, or missionId. Those identifiers
+let your application reconnect after a timeout or restart without creating
+duplicate work.
 
-The SDK also exposes the standards-shaped A2A boundary. Discover the remote
-Agent Card, submit a durable task, stream or subscribe to updates, and attach
-an encrypted callback for long-running work:
+## Stable identity
 
-```ts
-const card = await chusky.a2a.card();
-const task = await chusky.a2a.send("Prepare a verified launch brief.", {
-  idempotencyKey: "a2a-launch-brief-2026-09-22",
-});
+userId is the isolation boundary for SDK state. Chusky uses it to scope
+threads, runs, memory, files, artifacts, approvals, tasks, and connected
+accounts.
 
-// For image tasks, upload with chusky.files.upload() first. A2A accepts only
-// available owner-scoped Chusky file IDs, never inline bytes or arbitrary URLs.
-const imageTask = await chusky.a2a.send({
-  text: "Transfer this image to the connected social account.",
-  attachments: [image.id],
-}, { idempotencyKey: "image-transfer-2026-09-25" });
+Use the same stable value whenever the same person or tenant returns. Do not
+derive it from an unverified display name, a phone number, or a channel
+message. Do not use the root operator identity for normal end-user traffic.
 
-const callback = await chusky.a2a.createPushNotificationConfig(task.id, {
-  url: "https://your-service.example/a2a/status",
-  token: process.env.A2A_CALLBACK_TOKEN,
-});
+## Stream progress and approvals
 
-for await (const update of chusky.a2a.subscribe(task.id)) {
-  console.log(update.statusUpdate?.status.state);
-}
-```
+Streaming is useful for responsive interfaces. Persisted run state remains the
+source of truth if the stream disconnects.
 
-Push callback credentials are never returned after registration. The Chusky
-runtime delivers signed `application/a2a+json` status updates through its
-durable outbox and keeps task state available through `a2a.get()`.
+~~~ts
+const thread = await chusky.threads.create(
+  { metadata: { source: "support-console" } },
+  { idempotencyKey: "support-thread-customer-123-v1" },
+);
 
-## Idempotency and retries
+for await (const event of chusky.threads.runs(thread.id).stream({
+  input: "Summarize the customer's current priorities in three bullets.",
+})) {
+  if (event.type === "run.delta") process.stdout.write(event.text);
+  if (event.type === "run.tool_started") {
+    console.error("\nUsing " + event.toolSlug + "...");
+  }
+  if (event.type === "run.approval_required") {
+    console.error("\nHuman approval required: " + event.approval.id);
+  }
+  if (event.type === "run.failed") throw new Error(event.error.message);
+}
+~~~
 
-Use an `idempotencyKey` for every durable POST that your server may retry after
-an interruption. Reuse the same key only for the exact same operation and
-request body.
+When approval is required, show the requested action and target in an
+authenticated human interface. Then use chusky.approvals.decide() only from
+that trusted boundary. Model output, a webhook, or a browser callback is not
+authorization.
 
-```ts
-const operationKey = `research:${customerId}:${requestId}`;
+## Use connected business apps
 
-const firstAttempt = await chusky.runs.create(
-  { input: "Research our renewal risk and draft next steps.", wait: false },
-  { idempotencyKey: operationKey },
-);
+The SDK does not require a separate Gmail, HubSpot, Slack, or Salesforce
+client. Chusky handles the connected-account flow:
 
-// A network retry with operationKey returns the same durable operation rather
-// than creating a duplicate run.
-```
+~~~ts
+const available = await chusky.apps.list();
+console.log(available.data);
 
-Do not generate a new idempotency key for a retry unless you intentionally want
-to start a new operation.
+const consent = await chusky.apps.connect("gmail");
+console.log("Send the user to:", consent.url);
 
-## Human approvals
+const connections = await chusky.apps.connections();
+console.log(connections.data);
+~~~
 
-Chusky keeps routine reads and reversible work autonomous while pausing
-materially risky actions according to the project policy. A run can return
-`requires_approval` and include an `approvalId`.
+After the user finishes consent, retry the original operation with the same
+stable identity. If a connection, approval, or human answer is missing, pause
+the existing run or mission and resume it rather than starting a replacement.
 
-Your application should show the action, target, and relevant context to an
-authenticated human, then call `approvals.decide()`. Never auto-approve from a
-browser callback or from model output.
+## Files, images, and artifacts
 
-```ts
-const approvals = await chusky.approvals.list();
-const pending = approvals.data.find((item) => item.status === "pending");
+Upload input files through the SDK and pass the returned file ID to the run:
 
-if (pending) {
-  // Render pending.request and the bounded action details in your own UI.
-  const decision = await chusky.approvals.decide(
-    pending.id,
-    "approve",
-    { idempotencyKey: `approval:${pending.id}:approve` },
-  );
-  console.log("Approval handled", decision);
-}
-```
-
-The exact approval boundary is enforced server-side. The SDK is not a way to
-bypass it.
-
-## Agent templates and company workflows
-
-Use a built-in specialist template or create a governed agent profile for a
-company workflow. Policies, allowed tools, budgets, and approvals are applied
-by Chusky before execution.
-
-```ts
-const templates = await chusky.agents.templates();
-console.log(templates.data.map((template) => template.slug));
-
-const agent = await chusky.agents.create({
-  template: "lead-research",
-  name: "Fintech lead scout",
-  instructions: "Return sourced, deduplicated company profiles.",
-  policy: {
-    tools: {
-      allow: ["crm.read", "web.search", "email.draft"],
-      requireApproval: ["email.send", "crm.write"],
-    },
-    budget: { duration: "30m", maxToolCalls: 80, maxCost: 8 },
-  },
+~~~ts
+import { readFile } from "node:fs/promises";
+
+const imageBytes = new Uint8Array(await readFile("launch.png"));
+const image = await chusky.files.upload({
+  name: "launch.png",
+  contentType: "image/png",
+  data: imageBytes,
 });
 
 const { thread, run } = await chusky.runs.create(
   {
-    agentId: agent.id,
-    input: "Find qualified fintech leads with more than 50 employees.",
+    input: "Use this image in the prepared social post, then wait for approval.",
+    attachments: [image.id],
     wait: false,
   },
-  { idempotencyKey: "acme-fintech-leads-2026-09-21" },
+  { idempotencyKey: "launch-post-image-customer-123-v1" },
 );
 
-console.log(`Run ${run.id} started in thread ${thread.id}`);
-```
+console.log(thread.id, run.id, image.id);
+~~~
 
-Composio owns OAuth, connected accounts, token refresh, and external tool
-execution. Chusky owns the agent profile, policy, orchestration, approvals,
-durability, and result delivery.
+Use chusky.images.get(imageId) for a fresh, short-lived download URL for a
+generated image. Use chusky.artifacts.get() and chusky.artifacts.download() for
+generated documents and other artifacts.
+
+Do not send raw bytes, credentials, or arbitrary public URLs inside a prompt
+and assume a provider received them. Verify the file belongs to the current
+identity and confirm the provider receipt before claiming an external post or
+message succeeded.
 
 ## Durable missions
 
-Use missions when the work has multiple steps, dependencies, budgets, evidence,
-waits, or a definition of done. The mission API supports pause, resume,
-repair, cancellation, provider-event continuation, replanning, proof, and
-verification.
-
-```ts
-const mission = await chusky.missions.create({
-  title: "Qualified fintech leads",
-  objective: "Find 20 fintech companies matching our ICP.",
-  definitionOfDone: "Every lead has a source, qualification reason, and CRM-ready payload.",
-  verificationMode: "strict",
-  requiredEvidence: ["source URL", "qualification assertion", "deduplication check"],
-  steps: [
-    { id: "research", title: "Research companies", objective: "Collect source-backed facts." },
-    { id: "qualify", title: "Qualify leads", objective: "Apply the ICP and remove duplicates.", dependsOn: ["research"] },
-    { id: "prepare", title: "Prepare CRM payload", objective: "Create an approval-ready import.", dependsOn: ["qualify"] },
-  ],
-  maxDurationSeconds: 3 * 60 * 60,
-  maxSteps: 30,
-  maxToolCalls: 100,
-  maxCost: 15,
-}, { idempotencyKey: "acme-lead-mission-2026-09-21" });
+Use a mission when a job has multiple steps, dependencies, budgets, waits, or a
+definition of done:
+
+~~~ts
+const mission = await chusky.missions.create(
+  {
+    title: "Turn a qualified inquiry into a confirmed order",
+    objective: "Research the buyer, answer questions, and prepare an offer.",
+    definitionOfDone:
+      "The CRM record is updated, the offer is prepared, and no purchase is made without approval.",
+    verificationMode: "strict",
+    requiredEvidence: ["CRM record", "buyer requirements", "approval-ready offer"],
+    steps: [
+      { id: "research", title: "Research buyer", objective: "Collect verified facts." },
+      { id: "qualify", title: "Qualify opportunity", objective: "Check fit and budget.", dependsOn: ["research"] },
+      { id: "offer", title: "Prepare offer", objective: "Draft the bounded offer.", dependsOn: ["qualify"] },
+    ],
+    maxDurationSeconds: 3 * 60 * 60,
+    maxSteps: 30,
+    maxToolCalls: 100,
+    maxCost: 15,
+  },
+  { idempotencyKey: "buyer-inquiry-customer-123-v1" },
+);
 
 const proof = await chusky.missions.proof(mission.id);
 console.log(proof.status, proof.nextAction, proof.verification);
-```
-
-Treat `proof()` and `verify()` as the external completion record. Do not claim
-that a mission completed because a model produced a plausible paragraph; use
-the recorded steps, evidence, and verification state.
-
-## Shared context, departments, and outcomes
-
-The operating layer lets applications preserve useful, sensitivity-aware
-context and hand work between specialized departments.
-
-```ts
-await chusky.context.save({
-  scope: "customer",
-  scopeId: "customer_123",
-  kind: "preference",
-  key: "renewal_window",
-  value: "Customer prefers renewal discussions in October.",
-  source: "crm",
-  confidence: 0.9,
-  sensitivity: "normal",
-});
+~~~
 
-const salesContext = await chusky.context.list({
-  scope: "customer",
-  scopeId: "customer_123",
-  purpose: "renewal",
-});
+Missions support pause(), resume(), cancel(), repair(), replan(), evidence(),
+and verify(). Use proof and fresh provider readbacks as the completion record;
+a plausible model paragraph is not proof that a business action happened.
 
-const packet = await chusky.departments.handoff("customer-success", {
-  objective: "Prepare a renewal risk review for the account team.",
-  inputs: { customerId: "customer_123" },
-  constraints: ["Use verified CRM facts only."],
-  evidenceRequired: ["account health source", "open risk owner"],
-  approvalBoundary: "Draft only; do not contact the customer.",
-});
+## Agent-to-agent work
 
-console.log(packet.id, packet.status, salesContext.data.length);
-```
+The SDK includes a typed A2A client for durable delegated tasks:
 
-## Agent-to-agent (A2A)
-
-The SDK includes a typed client for Chusky's standards-shaped A2A 1.0
-boundary. It uses the same project API key and stable user identity as the
-rest of the SDK, so delegated work stays owner-scoped and durable.
-
-```ts
+~~~ts
 const card = await chusky.a2a.card();
-console.log(card.protocolVersion, card.skills?.map((skill) => skill.id));
+console.log(card.skills);
 
 const task = await chusky.a2a.send("Prepare a verified launch brief.", {
-  idempotencyKey: "launch-brief-2026-09-22",
+  idempotencyKey: "a2a-launch-brief-v1",
 });
 
 const current = await chusky.a2a.get(task.id);
-const page = await chusky.a2a.list(undefined, 20);
-console.log(current.status.state, page.tasks.length);
+console.log(current.status.state);
+~~~
 
-if (current.status.state !== "TASK_STATE_COMPLETED") {
-  await chusky.a2a.cancel(current.id);
-}
-```
-
-Use `a2a.card()` for discovery, `a2a.send()` for a durable delegated task,
-`a2a.get()` or `a2a.list()` for status, and `a2a.cancel()` for cancellation.
-The SDK sends A2A JSON-RPC over the authenticated `/a2a/rpc` boundary and
-does not expose private prompts, credentials, or unscoped tenant data. Image
-references use Chusky's `data.chuskyFileIds` message-part extension and are
-validated against the caller's available image files before the durable task
-is queued.
-
-## Files and artifacts
-
-File uploads use a short-lived storage URL. The SDK also exposes artifact
-metadata and verified downloads for files generated by Chusky.
-
-```ts
-const body = new TextEncoder().encode("customer_id,renewal_date\n123,2026-10-01\n");
-const upload = await chusky.files.create({
-  name: "renewals.csv",
-  contentType: "text/csv",
-  size: body.byteLength,
-}, { idempotencyKey: "upload-renewals-2026-09-21" });
-
-const response = await fetch(upload.uploadUrl, {
-  method: "PUT",
-  headers: { "Content-Type": "text/csv" },
-  body,
-});
-if (!response.ok) throw new Error(`Upload failed: ${response.status}`);
+Use a2a.stream(), a2a.subscribe(), or
+a2a.createPushNotificationConfig() for long-running delegated work.
+Attachments must be owner-scoped Chusky file IDs, not inline bytes or arbitrary
+URLs.
 
-const file = await chusky.files.complete(upload.id);
-console.log(file.id, file.status);
-```
+## Idempotency, retries, and errors
 
-## Webhooks
+Use an idempotencyKey for every durable write that your server might retry.
+Reuse the same key only for the same operation and request body.
 
-Register a server endpoint for durable delivery notifications and make the
-handler idempotent by recording the delivery ID before applying the event.
+~~~ts
+const key = "research:" + customerId + ":" + requestId;
 
-```ts
-const webhook = await chusky.webhooks.create(
-  "https://app.example.com/api/chusky/events",
-  { idempotencyKey: "webhook-register-events-v1" },
+const first = await chusky.runs.create(
+  { input: "Research renewal risk and draft next steps.", wait: false },
+  { idempotencyKey: key },
 );
 
-const deliveries = await chusky.webhooks.deliveries(webhook.id);
-console.log(deliveries.data.map((delivery) => delivery.status));
-```
+// Retrying with key returns the same durable operation rather than a duplicate.
+~~~
+
+Catch the typed errors when you need specific recovery:
+
+~~~ts
+import {
+  ChuskyAuthenticationError,
+  ChuskyRateLimitError,
+} from "@chusky/sdk";
+
+try {
+  await chusky.usage.get();
+} catch (error) {
+  if (error instanceof ChuskyRateLimitError) {
+    console.log("Retry after:", error.retryAfter);
+  } else if (error instanceof ChuskyAuthenticationError) {
+    console.log("Check the API key and user identity.");
+  }
+  throw error;
+}
+~~~
 
-## Operator provisioning
+If a request times out, read the run or task by ID before retrying. A lost HTTP
+response does not prove that durable work failed.
 
-`createChuskyAdmin()` is for a trusted operator service only. It uses the root
-project key to provision scoped project keys and must never be shipped to an
-end-user application.
+## Resource map
 
-```ts
-import { createChuskyAdmin } from "@chusky/sdk";
+| Resource | What it helps you build |
+| --- | --- |
+| threads, runs, tasks | Conversations, durable execution, and recovery |
+| agents, tools, skills | Governed agent profiles and available capabilities |
+| apps, mcp, channels, devices | Connected accounts, external MCP servers, delivery, and device access |
+| missions, workflows, outcomes, departments | Multi-step business processes and handoffs |
+| files, images, artifacts, videos | Inputs and generated outputs |
+| context, memory, scratchpad | Explicit operating context and temporary notes |
+| meetings, calls | Meeting preparation, joining, and voice operations |
+| reminders, jobs, webhooks, audit, usage | Scheduled work, delivery, traceability, and usage |
+| autonomy, operator, company | Readiness, reliability, business queues, and company telemetry |
+
+The public package also exports the dependency-free
+@chusky/sdk/widget entry point for a browser chat element. The browser widget
+talks to your own server endpoint; your server keeps the API key private.
+
+~~~ts
+import { defineChuskyChat } from "@chusky/sdk/widget";
+
+defineChuskyChat();
+~~~
+
+~~~html
+<chusky-chat
+  endpoint="/api/chusky/chat"
+  title="Talk to our assistant"
+  greeting="How can we help?"
+></chusky-chat>
+~~~
 
-const admin = createChuskyAdmin({
-  apiKey: process.env.CHUSKY_PROJECT_KEY!,
-  baseUrl: process.env.CHUSKY_BASE_URL,
-});
+## Examples
 
-const project = await admin.projects.create({
-  name: "Acme production",
-  scopes: ["runs:create", "runs:read", "missions:read", "missions:create"],
-});
+The examples directory contains runnable TypeScript examples:
 
-console.log(project.key); // Store once. It is not returned by list().
-```
+| Example | Demonstrates |
+| --- | --- |
+| [quickstart.ts](examples/quickstart.ts) | Start a durable run and wait for completion |
+| [streaming.ts](examples/streaming.ts) | Stream deltas, tool activity, and approval events |
+| [company-agent.ts](examples/company-agent.ts) | Create a governed company agent |
+| [mission.ts](examples/mission.ts) | Define steps, evidence, and mission proof |
+| [approvals.ts](examples/approvals.ts) | Display and decide a pending approval |
+| [context-and-departments.ts](examples/context-and-departments.ts) | Save context and create a department handoff |
+| [files.ts](examples/files.ts) | Upload bytes through the SDK |
+| [webhooks.ts](examples/webhooks.ts) | Register a delivery endpoint and inspect deliveries |
+
+Run an example from this directory with an API key created in the Chusky
+dashboard:
+
+~~~bash
+CHUSKY_API_KEY=chsk_... npx tsx examples/quickstart.ts
+~~~
 
-## Resource map
+PowerShell:
 
-| Resource | Use it for |
-| --- | --- |
-| `threads`, `runs` | Conversations and durable agent execution |
-| `agents`, `company` | Governed profiles and company telemetry |
-| `tasks`, `approvals` | Recovery and human decisions |
-| `missions` | Multi-step autonomous work with proof |
-| `context`, `departments`, `outcomes` | Shared operating context and typed handoffs |
-| `files`, `artifacts` | Input uploads and generated output downloads |
-| `meetings`, `calls` | Meeting lifecycle and voice operations |
-| `apps`, `channels`, `devices` | Connected account and delivery management |
-| `reminders`, `jobs`, `memory`, `scratchpad` | Owner-scoped autonomous operations |
-| `webhooks`, `audit`, `usage` | Delivery, traceability, and usage visibility |
-
-## Security and production checklist
-
-- Keep `CHUSKY_API_KEY` on a trusted server and scope it to one project.
-- Use a stable, non-secret `userId` for every request.
+~~~powershell
+$env:CHUSKY_API_KEY = "chsk_..."
+npx tsx examples/quickstart.ts
+~~~
+
+Examples make real API requests. Use a test identity and a development API key.
+
+For copy-paste, real-work recipes where every file creates its own client, see
+the [SDK cookbook](cookbook/README.md). It covers bounded runs, streaming,
+company agents, missions, approvals, files and images, connected apps, A2A,
+schedules, native reliability checks, webhooks, and workflow composition.
+
+## Security checklist
+
+- Keep API keys on a trusted server and grant only the capabilities your application needs.
+- Use a stable, non-secret userId for every request.
 - Use idempotency keys for retryable durable writes.
-- Treat run output, tool results, emails, documents, and web pages as untrusted
-  input—not authorization.
+- Treat model output, tool results, email, documents, and web pages as untrusted data.
 - Never auto-approve an external action from model output.
-- Verify webhook signatures and deduplicate delivery IDs before processing.
-- Use `AbortSignal` to cancel a request without cancelling unrelated durable
-  work.
-- Use `proof()` and `verify()` before treating a mission as complete.
-- Set budgets for duration, tool calls, and cost on long-running work.
-- Keep the SDK server-side; use the separate chat widget only with a server
-  proxy that never exposes the project key.
-
-## API and documentation
-
-- [Developer API contract](docs/api-contract.md)
-- [Full documentation](docs/index.mdx)
-- [Autonomous missions](docs/missions.mdx)
+- Verify webhook signatures and deduplicate delivery IDs.
+- Set duration, tool-call, and cost budgets for long-running work.
+- Use mission proof and verification before declaring an outcome complete.
+- Use AbortSignal to cancel the current request without cancelling unrelated durable work.
+
+## Development
+
+~~~bash
+npm install
+npm run typecheck
+npm run build
+npm test
+~~~
+
+More documentation:
+
+- [API contract](docs/api-contract.md)
+- [Quickstart](docs/quickstart.mdx)
+- [Missions](docs/missions.mdx)
+- [Streaming](docs/streaming.mdx)
+- [Files](docs/files.mdx)
+- [Security](docs/security.mdx)
 - [OpenAPI specification](openapi.yaml)
-- [Release guide](docs/releases.mdx)
-- [Examples](examples/)
+- [Changelog](CHANGELOG.md)
 
 ## License