ql-agent-sdk 1.0.0 → 1.0.2

package/README.md

@@ -1,8 +1,14 @@
 # ql-agent-sdk
 
-TypeScript SDK for the **Quanton Labs** agent platform API (v1). Integrates your application with the 8 specialized agents, capabilities, workflows, and background tasks. Zero runtime dependencies — built on native `fetch` and Web Streams.
+TypeScript SDK for the **Quanton Labs** agent platform API (v1). Integrate your application with 8 specialized AI agents, capabilities, workflows, and background tasks.
 
-> Base URL defaults to `https://app.quantonlabs.com`. Override with `baseUrl` or the `QL_BASE_URL` env var.
+- **Zero runtime dependencies** — built on native `fetch` and Web Streams
+- **Full TypeScript** — all request/response types exported
+- **ESM + CJS** — works in Node, Bun, Deno, Next.js, and edge runtimes
+
+> Base URL defaults to `https://app.quantonlabs.com`. Override with `baseUrl` option or the `QL_BASE_URL` environment variable.
+
+---
 
 ## Install
 
@@ -10,20 +16,25 @@ TypeScript SDK for the **Quanton Labs** agent platform API (v1). Integrates your
 npm install ql-agent-sdk
 # or
 pnpm add ql-agent-sdk
+# or
+yarn add ql-agent-sdk
 ```
 
-Requires **Node.js 18+** (native `fetch`). Works in Node, Bun, Deno, and browser/edge runtimes that provide `fetch` and Web Streams.
+Requires **Node.js 18+** (native `fetch`).
 
-## Quick start
+---
+
+## Quick Start
 
 ```ts
 import { QLClient } from "ql-agent-sdk";
 
 const ql = new QLClient({ apiKey: process.env.QL_API_KEY! });
 
-// Discover agents
+// Discover available agents
 const { agents } = await ql.agents.list();
 console.log(agents.map((a) => a.id));
+// → ["governing", "finance", "marketing", "inventory", "customer", "developer", "operations", "research"]
 
 // Chat with an agent (non-streaming)
 const reply = await ql.agents.chat({
@@ -33,163 +44,705 @@ const reply = await ql.agents.chat({
 console.log(reply.content);
 ```
 
+---
+
 ## Configuration
 
 ```ts
-new QLClient({
-  apiKey,                 // required — your Bearer API key (never logged/exposed)
-  baseUrl,                // optional — defaults to QL_BASE_URL or https://app.quantonlabs.com
-  fetch: customFetch,     // optional — override for tests/proxies/custom runtimes
+const ql = new QLClient({
+  apiKey,               // required — your Bearer API key (ql_live_...)
+  baseUrl,              // optional — defaults to QL_BASE_URL or https://app.quantonlabs.com
+  fetch: customFetch,   // optional — override for tests/proxies/custom runtimes
 });
 ```
 
-`apiKey` is held in a private field and is never returned by the client, included in errors, or logged.
+The `apiKey` is held in a private field. It is **never** returned by the client, included in error messages, or logged.
+
+---
+
+## Authentication
+
+All API calls use **Bearer token authentication** with your API key:
+
+```
+Authorization: Bearer ql_live_your_key_here
+```
+
+Create keys in your Quanton Labs dashboard → **API Keys** page. Each key is scoped to a single workspace.
+
+### Scope Requirements
+
+| Scope | Grants access to |
+|-------|-----------------|
+| `workspace` | `ql.workspace.get()` |
+| `agents` | `ql.agents.list()`, `ql.agents.get()` |
+| `capabilities` | `ql.agents.capabilities()`, `ql.agents.runCapability()` |
+| `chat` | `ql.agents.chat()`, `ql.agents.chatStream()` |
+| `messages` | `ql.agents.history()` |
+| `workflows` | `ql.workflows.run()`, `ql.workflows.getRun()` |
+| `tasks` | `ql.tasks.create()`, `ql.tasks.get()` |
+| `*` | All of the above (default for new keys) |
+
+---
+
+## API Reference
+
+### Response Envelope
+
+All non-streaming endpoints return a consistent envelope:
+
+**Success:**
+```json
+{ "ok": true, "data": { ... } }
+```
+
+**Error:**
+```json
+{ "ok": false, "error": { "code": "not_found", "message": "Agent not found: foo" } }
+```
+
+The SDK unwraps `data` for you and throws a typed `QLError` on errors. You never see the envelope directly.
 
-## API reference
+---
 
 ### Workspace
+
+#### `ql.workspace.get()` → `Promise<Workspace>`
+
+**Scope:** `workspace`
+
+Returns the workspace bound to your API key.
+
+**Response (200):**
+```json
+{
+  "_id": "6adf926f6f87c9ab86f32c0e",
+  "name": "Robin",
+  "plan": "standard",
+  "createdAt": "2026-10-26T17:48:31.038Z",
+  "updatedAt": "2026-10-27T11:56:44.074Z"
+}
+```
+
+**TypeScript:**
 ```ts
-const ws = await ql.workspace.get();          // -> { _id, name, plan, createdAt, updatedAt }
+const ws = await ql.workspace.get();
+ws._id;      // string
+ws.name;     // string
+ws.plan;     // "standard" | "premium" | "enterprise" | undefined
+ws.createdAt; // string (ISO 8601)
 ```
 
+---
+
 ### Agents
-```ts
-const { agents } = await ql.agents.list();                 // AgentListResult
-const detail = await ql.agents.get("finance");             // AgentDetail (agent + capabilities)
-const caps   = await ql.agents.capabilities("finance");    // CapabilitiesResult
 
-// Run a capability ("feature"). The result is a discriminated union:
+#### `ql.agents.list()` → `Promise<AgentListResult>`
+
+**Scope:** `agents`
+
+Lists all 8 available agents with their capability counts.
+
+**Response (200):**
+```json
+{
+  "agents": [
+    {
+      "id": "governing",
+      "name": "Governing Agent",
+      "domain": "orchestration",
+      "description": "Coordinates all other agents...",
+      "icon": "brain",
+      "tags": ["coordination", "reasoning"],
+      "capabilityCount": 20
+    }
+  ]
+}
+```
+
+#### `ql.agents.get(agentId)` → `Promise<AgentDetail>`
+
+**Scope:** `agents`
+
+Returns an agent's details and full capability list.
+
+**Parameters:**
+- `agentId: string` — agent slug (e.g. `"finance"`, `"governing"`) or ObjectId
+
+**Response (200):**
+```json
+{
+  "agent": {
+    "id": "finance",
+    "name": "Finance Agent",
+    "domain": "finance",
+    "description": "Handles financial analysis...",
+    "icon": "dollar-sign",
+    "tags": ["accounting", "budgeting"]
+  },
+  "capabilities": [
+    {
+      "id": "invoice",
+      "name": "Invoice Generator",
+      "description": "Generate formatted invoices from data",
+      "category": "documents",
+      "params": [
+        { "key": "data", "label": "Data", "kind": "textarea", "required": true }
+      ],
+      "templates": [
+        { "label": "Monthly Report", "values": { "data": "Revenue | 12000\nCosts | 4000" } }
+      ]
+    }
+  ]
+}
+```
+
+**Errors:**
+- `404 not_found` — agent slug doesn't exist
+
+#### `ql.agents.capabilities(agentId)` → `Promise<CapabilitiesResult>`
+
+**Scope:** `capabilities`
+
+Returns just the capability list for an agent (lighter than `get`).
+
+**Response (200):**
+```json
+{
+  "agentId": "finance",
+  "capabilities": [ ... ]
+}
+```
+
+#### `ql.agents.runCapability(agentId, input)` → `Promise<RunCapabilityResult>`
+
+**Scope:** `capabilities`
+
+Executes a specific capability (feature) on an agent.
+
+**Parameters:**
+- `agentId: string` — agent slug
+- `input.capId: string` — capability ID (from the capabilities list)
+- `input.params?: Record<string, unknown>` — capability-specific parameters
+
+**Response (200):**
+```json
+{
+  "result": {
+    "type": "html",
+    "html": "<div class=\"invoice\">...</div>"
+  }
+}
+```
+
+The `result` is a **discriminated union** — check `result.type`:
+
+| `type` | Fields | When |
+|--------|--------|------|
+| `"text"` | `content: string` | Plain text output |
+| `"json"` | `data: unknown` | Structured JSON |
+| `"html"` | `html: string` | HTML content (renderable) |
+| `"file"` | `url, filename, mime` | Generated file (image, PDF, etc.) |
+
+**Example:**
+```ts
 const { result } = await ql.agents.runCapability("finance", {
   capId: "invoice",
   params: { data: "Revenue | 12000\nCosts | 4000" },
 });
-if (result.type === "html") render(result.html);
-else if (result.type === "json") use(result.data);
-else if (result.type === "text") print(result.content);
-// result.type === "file" -> { url, filename, mime }
 
-// Chat (non-streaming)
-const out = await ql.agents.chat({ agentId: "marketing", messages: [...] }); // ChatResult
+if (result.type === "html") {
+  document.body.innerHTML = result.html;
+} else if (result.type === "json") {
+  console.log(result.data);
+} else if (result.type === "text") {
+  console.log(result.content);
+} else if (result.type === "file") {
+  window.open(result.url); // download
+}
 ```
 
-### Streaming chat (SSE)
-`agents.chatStream` returns an **async iterable** of events. Stop it with an `AbortController`.
+---
+
+### Chat
 
+#### `ql.agents.chat(input)` → `Promise<ChatResult>`
+
+**Scope:** `chat`
+
+Non-streaming chat with an agent. Waits for the full response.
+
+**Parameters:**
+- `agentId: string` — agent slug
+- `messages: ChatMessage[]` — conversation history (newest last)
+- `userId?: string` — optional internal user ID (defaults to workspace)
+- `response_format?: object` — optional OpenRouter format hint
+
+**Response (200):**
+```json
+{
+  "content": "Based on your data, Q3 revenue was $120K...",
+  "toolCalls": 2,
+  "iterations": 3,
+  "duration": "4.21s"
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `content` | `string` | The agent's full text response |
+| `toolCalls` | `number` | How many tool calls were made during reasoning |
+| `iterations` | `number` | Tool loop iterations |
+| `duration` | `string` | Human-readable execution time |
+
+**Example:**
+```ts
+const reply = await ql.agents.chat({
+  agentId: "finance",
+  messages: [
+    { role: "user", content: "What was our profit margin last month?" },
+  ],
+});
+console.log(reply.content);
+```
+
+---
+
+#### `ql.agents.chatStream(input, opts?)` → `AsyncIterable<ChatStreamEvent>`
+
+**Scope:** `chat`
+
+Streaming chat — yields incremental events as the agent responds.
+
+**Parameters:**
+- Same as `chat()` above
+- `opts.signal?: AbortSignal` — abort the stream at any time
+
+**Yielded events:**
+```ts
+type ChatStreamEvent =
+  | { type: "delta"; content?: string; reasoning?: string }  // incremental piece
+  | { type: "done"; content: string; reasoning?: string };   // final accumulated text
+```
+
+| Event | When | Fields |
+|-------|------|--------|
+| `delta` | For each token/chunk from the model | `content` (text delta), `reasoning` (thinking delta, if model supports it) |
+| `done` | Once at the end | `content` (full accumulated text), `reasoning` (full reasoning, if any) |
+
+**Example:**
 ```ts
 import { QLClient } from "ql-agent-sdk";
 
 const ql = new QLClient({ apiKey: process.env.QL_API_KEY! });
 const controller = new AbortController();
 
-// e.g. abort after 30s or on user action
+// Optional: auto-abort after 30s
 const timer = setTimeout(() => controller.abort(), 30_000);
 
 let full = "";
 try {
   for await (const ev of ql.agents.chatStream(
-    { agentId: "governing", messages: [{ role: "user", content: "Hello" }] },
+    { agentId: "governing", messages: [{ role: "user", content: "Explain quantum computing" }] },
     { signal: controller.signal },
   )) {
     if (ev.type === "delta") {
-      process.stdout.write(ev.content ?? "");   // incremental text
+      process.stdout.write(ev.content ?? ""); // print incrementally
       full += ev.content ?? "";
     } else if (ev.type === "done") {
-      full = ev.content;                        // final accumulated text
+      full = ev.content; // final text (replaces accumulated)
     }
   }
 } catch (err) {
-  if ((err as any)?.code === "aborted") console.log("stopped by user");
+  if ((err as any)?.code === "aborted") console.log("\n[stopped by user]");
 } finally {
   clearTimeout(timer);
 }
 ```
 
-The stream is robust to chunk boundaries, CRLF/LF endings, multiple events per chunk, a final event without a trailing newline, `[DONE]`, and malformed JSON (skipped).
+**SSE wire format** (if you ever need to parse it manually):
+```
+data: {"id":"gen-...","choices":[{"delta":{"content":"Hel"}}]}
+
+data: {"id":"gen-...","choices":[{"delta":{"content":"lo"}}]}
+
+data: [DONE]
+
+```
+Events are separated by blank lines. `data: [DONE]` signals the end.
+
+---
+
+### History / Messages
+
+#### `ql.agents.history(agentId, opts?)` → `Promise<HistoryPage>`
+
+**Scope:** `messages`
+
+Returns paginated conversation history for an agent (newest first).
+
+**Parameters:**
+- `agentId: string` — agent slug
+- `opts.limit?: number` — page size, 1–100 (default 20)
+- `opts.before?: string` — cursor from previous page's `nextBefore`
+- `opts.userId?: string` — optional filter by user
+
+**Response (200):**
+```json
+{
+  "agentId": "finance",
+  "limit": 20,
+  "nextBefore": "6ae0d96274f1cf895ef06e0c",
+  "items": [
+    {
+      "id": "6ae0d963...",
+      "role": "user",
+      "content": "What was our profit margin?",
+      "toolCalls": [],
+      "status": "completed",
+      "timestamp": "2026-10-27T14:32:00.000Z"
+    },
+    {
+      "id": "6ae0d962...",
+      "role": "assistant",
+      "content": "Based on your records...",
+      "reasoning": "Let me check the financial data...",
+      "toolCalls": [{ "name": "db_query", ... }],
+      "status": "completed",
+      "timestamp": "2026-10-27T14:32:05.000Z"
+    }
+  ]
+}
+```
 
-### History / pagination
-`agents.history` returns newest-first pages. Walk them with the `nextBefore` cursor until it is `null`.
+| Field | Description |
+|-------|-------------|
+| `nextBefore` | Cursor for next page. `null` when no more pages. |
+| `items[].role` | `"user"` or `"assistant"` |
+| `items[].content` | Message text (may be null for tool-only messages) |
+| `items[].reasoning` | Model's thinking (if supported by the model) |
+| `items[].toolCalls` | Array of tool invocations made during this message |
+| `items[].status` | `"completed"`, `"processing"`, or `"failed"` |
 
+**Walking all pages:**
 ```ts
-const ids: string[] = [];
+const allMessages = [];
 let before: string | undefined;
+
 do {
   const page = await ql.agents.history("finance", { limit: 50, before });
-  for (const m of page.items) ids.push(m.id);
-  before = page.nextBefore ?? undefined;   // null when exhausted
+  allMessages.push(...page.items);
+  before = page.nextBefore ?? undefined; // null when exhausted
 } while (before);
+
+console.log(`${allMessages.length} total messages`);
 ```
 
+---
+
 ### Workflows
-```ts
-const start = await ql.workflows.run("6adf929d6f87c9ab86f32c19", { input: { a: 1 } }); // 202 -> { runId, status: "running" }
-const run = await ql.workflows.getRun(start.runId);   // poll -> WorkflowRun (status/output/error/durationMs/...)
+
+#### `ql.workflows.run(workflowId, input?)` → `Promise<WorkflowRunStart>`
+
+**Scope:** `workflows`
+
+Triggers a workflow execution. Returns immediately with a run ID (HTTP 202).
+
+**Parameters:**
+- `workflowId: string` — the workflow's ObjectId
+- `input?: { input?: Record<string, unknown> }` — optional input payload for the workflow
+
+**Response (202):**
+```json
+{
+  "runId": "6ae101c8...",
+  "status": "running"
+}
 ```
 
-### Tasks (background)
+**Errors:**
+- `400 validation_error` — invalid workflow ID format
+- `404 not_found` — workflow doesn't exist in this workspace
+
+#### `ql.workflows.getRun(runId)` → `Promise<WorkflowRun>`
+
+**Scope:** `workflows`
+
+Polls a workflow run's status.
+
+**Response (200):**
+```json
+{
+  "runId": "6ae101c8...",
+  "status": "completed",
+  "output": { "result": "..." },
+  "error": null,
+  "durationMs": 4523,
+  "startedAt": "2026-10-27T14:32:00.000Z",
+  "finishedAt": "2026-10-27T14:32:04.523Z"
+}
+```
+
+| `status` value | Meaning |
+|----------------|---------|
+| `"queued"` | Waiting to start |
+| `"running"` | Currently executing |
+| `"completed"` | Finished successfully — check `output` |
+| `"failed"` | Execution error — check `error` |
+| `"cancelled"` | Was cancelled |
+
+**Polling example:**
 ```ts
-const created = await ql.tasks.create({ agentId: "finance", title: "Monthly report", priority: "high" }); // 201 -> { taskId, status }
-const handle = ql.tasks.handle(created.taskId);
+const start = await ql.workflows.run("6adf929d6f87c9ab86f32c19", { input: { a: 1 } });
+
+// Poll until done
+let run;
+do {
+  await new Promise((r) => setTimeout(r, 2000));
+  run = await ql.workflows.getRun(start.runId);
+} while (run.status === "running" || run.status === "queued");
+
+if (run.status === "completed") console.log(run.output);
+else if (run.status === "failed") console.error(run.error);
+```
+
+---
+
+### Tasks (Background)
+
+#### `ql.tasks.create(input)` → `Promise<TaskCreated>`
+
+**Scope:** `tasks`
+
+Creates a background task. The task **starts executing immediately** on the server — you don't need to call another endpoint.
+
+**Parameters:**
+- `agentId: string` — which agent handles this task
+- `title: string` — human-readable name
+- `description?: string` — optional longer description
+- `input?: unknown` — payload for the agent (string, or `{ message }`, or `{ prompt }`)
+- `priority?: "low" | "medium" | "high" | "urgent"` — scheduling priority
+
+**Response (201):**
+```json
+{
+  "taskId": "6ae101b7...",
+  "status": "queued"
+}
+```
+
+**Errors:**
+- `400 validation_error` — missing `agentId` or `title`
+- `404 not_found` — unknown agent slug
+
+#### `ql.tasks.get(taskId)` → `Promise<Task>`
+
+**Scope:** `tasks`
+
+Single poll of a task's current state.
+
+**Response (200):**
+```json
+{
+  "taskId": "6ae101b7...",
+  "status": "completed",
+  "title": "Monthly Report",
+  "progress": {
+    "current": 100,
+    "total": 100,
+    "message": "Completed",
+    "updatedAt": "2026-10-27T19:53:23.117Z"
+  },
+  "result": "Here is your monthly report...",
+  "output": "Here is your monthly report...",
+  "error": null,
+  "createdAt": "2026-10-27T19:53:16.756Z",
+  "completedAt": "2026-10-27T19:53:23.117Z"
+}
+```
+
+| `status` value | Meaning | Check field |
+|----------------|---------|-------------|
+| `"queued"` | Waiting to start | — |
+| `"running"` | In progress | `progress.message` for current step |
+| `"retrying"` | Failed, will retry automatically | `error` for what went wrong |
+| `"completed"` | Done successfully | `result` / `output` for the answer |
+| `"failed"` | Permanently failed (max retries) | `error` for the reason |
+| `"cancelled"` | Was cancelled | — |
+
+#### `ql.tasks.handle(taskId)` → `TaskHandle`
+
+Returns a handle with `poll()` and `wait()` methods.
+
+**`handle.poll(signal?)`** — single fetch, returns current `Task` snapshot.
+
+**`handle.wait(opts?)`** — polls until terminal status with backoff.
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `intervalMs` | 2000 | Initial delay between polls (ms) |
+| `maxIntervalMs` | 15000 | Backoff cap (grows 1.5× per poll) |
+| `timeoutMs` | undefined (wait forever) | Throw after this many ms total |
+| `signal` | undefined | AbortSignal for cancellation |
+| `onTick` | undefined | Callback after each poll with latest snapshot |
 
-// One-shot poll
-const snapshot = await handle.poll();
+**Terminal states returned by `wait()`:**
+- `task.status === "completed"` → check `task.result`
+- `task.status === "failed"` → check `task.error`
+- `task.status === "cancelled"` → task was cancelled server-side
 
-// Wait until terminal (completed/failed/cancelled) with backoff + timeout + cancellation
-const done = await handle.wait({
-  intervalMs: 2000,      // initial delay
-  maxIntervalMs: 15000,  // backoff cap
-  timeoutMs: 5 * 60_000, // throw QLError(code="timeout") if exceeded
-  signal: controller.signal, // throw QLError(code="aborted") if aborted
+**Non-terminal exits (throws QLError):**
+- `err.code === "timeout"` → exceeded `timeoutMs`
+- `err.code === "aborted"` → `signal` was aborted
+
+**Example:**
+```ts
+const created = await ql.tasks.create({
+  agentId: "finance",
+  title: "Quarterly Report",
+  input: { message: "Generate a Q3 financial summary from our database." },
+  priority: "high",
 });
+
+const handle = ql.tasks.handle(created.taskId);
+
+try {
+  const done = await handle.wait({
+    intervalMs: 2000,
+    maxIntervalMs: 10000,
+    timeoutMs: 5 * 60_000, // 5 minute timeout
+    onTick: (task) => {
+      if (task.status === "running" && task.progress?.message) {
+        process.stdout.write(`\r${task.progress.message}`);
+      }
+    },
+  });
+
+  if (done.status === "completed") {
+    console.log("\n✓ Done:", done.result);
+  } else if (done.status === "failed") {
+    console.error("✗ Failed:", done.error);
+  }
+} catch (err) {
+  if ((err as any).code === "timeout") console.error("Timed out after 5 min");
+  if ((err as any).code === "aborted") console.log("Cancelled by user");
+}
 ```
 
-> **Task execution limitation:** `tasks.create` only **enqueues** a task. It may remain in the `queued` state until an existing worker/execution mechanism on the backend processes it — creating a task via this SDK does **not** trigger execution. `wait()` simply polls until the task reaches a terminal status (or you time out / abort).
+> **Note on execution:** Tasks execute in the server's process. If the server restarts mid-execution, the task will be recovered and retried on next startup (up to `maxRetries` times). For mission-critical workloads with strict durability requirements, consider a persistent queue backend.
 
-## Errors
+---
 
-All failures throw a typed `QLError`:
+## Error Handling
+
+All API failures throw a typed **`QLError`**:
 
 ```ts
 import { QLClient, QLError } from "ql-agent-sdk";
 
 try {
-  await ql.agents.chat({ ... });
+  await ql.agents.chat({ agentId: "finance", messages: [...] });
 } catch (err) {
   if (err instanceof QLError) {
-    err.status;    // HTTP status (401/403/404/409/400/500) when from an HTTP response
-    err.code;      // stable code: unauthorized | forbidden | not_found | conflict |
-                   //             validation_error | internal_error | network | aborted | timeout
-    err.message;   // human-readable (never includes the API key)
-    err.isAuthError / err.isAborted / err.isTimeout / err.isNetworkError
+    console.error(err.status);   // HTTP status code (401, 403, 404, etc.)
+    console.error(err.code);     // stable string code (see table below)
+    console.error(err.message);  // human-readable (never includes API key)
+
+    // Convenience booleans:
+    err.isAuthError;      // true for 401/403
+    err.isAborted;        // true for abort
+    err.isTimeout;        // true for wait() timeout
+    err.isNetworkError;   // true for connection failures
   }
 }
 ```
 
-| HTTP status | `code` | Meaning |
-|---|---|---|
-| 401 | `unauthorized` | missing/invalid/revoked API key |
-| 403 | `forbidden` | key lacks the required scope |
-| 404 | `not_found` | resource not found in this workspace |
-| 409 | `conflict` | conflict (e.g. duplicate) |
-| 400 | `validation_error` | bad request / invalid params |
-| 5xx | `internal_error` | server error |
+### Error Code Reference
+
+| HTTP Status | `code` | When it happens |
+|-------------|--------|-----------------|
+| 401 | `unauthorized` | Missing, invalid, or revoked API key |
+| 403 | `forbidden` | Key lacks the required scope for this endpoint |
+| 404 | `not_found` | Resource doesn't exist in your workspace (agent, workflow, task) |
+| 409 | `conflict` | Conflict (e.g. duplicate resource) |
+| 400 | `validation_error` | Malformed request body, missing required fields, invalid params |
+| 500 | `internal_error` | Server-side error (AI provider failure, DB issue, etc.) |
+| — | `network` | No HTTP response received (connection refused, DNS failure, timeout) |
+| — | `aborted` | Caller aborted via `AbortSignal` |
+| — | `timeout` | `wait()` exceeded its `timeoutMs` budget |
 
-Transport-level failures map to `network` (no HTTP response), `aborted` (caller aborted), and `timeout` (`wait()` exceeded its budget).
+### Common Error Scenarios
+
+```ts
+// 1. Expired/revoked key
+try {
+  await ql.workspace.get();
+} catch (e) {
+  if (e instanceof QLError && e.code === "unauthorized") {
+    console.log("API key is invalid or revoked. Generate a new one in your dashboard.");
+  }
+}
+
+// 2. Key doesn't have chat scope
+try {
+  await ql.agents.chat({ agentId: "finance", messages: [...] });
+} catch (e) {
+  if (e instanceof QLError && e.code === "forbidden") {
+    console.log("This key needs the 'chat' scope. Create a new key with broader scopes.");
+  }
+}
+
+// 3. AI provider error (transient)
+try {
+  await ql.agents.chat({ agentId: "governing", messages: [...] });
+} catch (e) {
+  if (e instanceof QLError && e.status === 500) {
+    console.log("AI service temporarily unavailable. Retry later.");
+  }
+}
+```
+
+---
 
 ## TypeScript
 
-The package ships full type declarations (`dist/index.d.ts` / `.d.cts`). All request/response types are exported:
+Full type declarations are included. All public types are exported:
 
 ```ts
 import type {
-  QLClientOptions, ChatInput, ChatResult, ChatStreamEvent,
-  AgentSummary, CapabilityInfo, CapabilityResult, HistoryPage,
-  WorkflowRun, Task, TaskCreateInput, WaitOptions, QLError,
+  QLClient,
+  QLClientOptions,
+  QLError,
+  // Request types
+  ChatInput,
+  RunCapabilityInput,
+  TaskCreateInput,
+  WaitOptions,
+  HistoryParams,
+  WorkflowRunInput,
+  // Response types
+  Workspace,
+  AgentSummary,
+  AgentDetail,
+  CapabilityInfo,
+  CapabilityResult,
+  ChatResult,
+  ChatStreamEvent,
+  HistoryPage,
+  MessageItem,
+  WorkflowRun,
+  Task,
+  TaskCreated,
+  // Constants
+  API_ERROR_CODES,
 } from "ql-agent-sdk";
 ```
 
-## Using it in a Next.js App Router (server-side)
+---
 
-In a **Route Handler** (`app/api/.../route.ts`) or a server Component — the SDK is safe to use on the server:
+## Using in Next.js App Router
+
+The SDK is safe to use **server-side** in Route Handlers or Server Components:
 
 ```ts
 // app/api/agent/route.ts
@@ -200,48 +753,97 @@ export const runtime = "nodejs"; // uses native fetch + Web Streams
 const ql = new QLClient({ apiKey: process.env.QL_API_KEY! });
 
 export async function POST(req: Request) {
+  const { message } = await req.json();
+
   try {
-    const { prompt } = await req.json();
-    const res = await ql.agents.chat({
+    const reply = await ql.agents.chat({
       agentId: "governing",
-      messages: [{ role: "user", content: prompt }],
+      messages: [{ role: "user", content: message }],
     });
-    return Response.json({ ok: true, content: res.content });
+    return Response.json({ text: reply.content });
   } catch (err) {
     if (err instanceof QLError) {
-      return Response.json({ ok: false, code: err.code, message: err.message }, { status: err.status ?? 500 });
+      return Response.json({ error: err.message }, { status: err.status ?? 500 });
     }
     throw err;
   }
 }
 ```
 
-For **streaming** to the browser from a Route Handler, forward the SDK's events as an SSE `ReadableStream` (see the streaming example above for consuming them).
+For **streaming** in a Route Handler:
+```ts
+export async function POST(req: Request) {
+  const { message } = await req.json();
+  const ql = new QLClient({ apiKey: process.env.QL_API_KEY! });
+
+  const stream = new ReadableStream({
+    async start(controller) {
+      try {
+        for await (const ev of ql.agents.chatStream({
+          agentId: "governing",
+          messages: [{ role: "user", content: message }],
+        })) {
+          if (ev.type === "delta" && ev.content) {
+            controller.enqueue(new TextEncoder().encode(ev.content));
+          }
+        }
+      } finally {
+        controller.close();
+      }
+    },
+  });
+
+  return new Response(stream, { headers: { "Content-Type": "text/plain" } });
+}
+```
 
-## Development
+---
 
-```bash
-npm install
-npm run typecheck   # tsc --noEmit
-npm run lint        # eslint (typescript-eslint)
-npm test            # vitest (unit: fetch, errors, SSE, polling, timeout, cancellation, pagination)
-npm run build       # tsup -> dist (ESM + CJS + .d.ts)
-```
+## Agent Reference
 
-## Publishing
+The platform includes 8 specialized agents. Each has 20 capabilities in its domain:
 
-This package is **not** published. To publish when ready (requires an npm account/org):
+| ID | Domain | Examples |
+|----|--------|----------|
+| `governing` | Orchestration | Coordinates other agents, complex multi-step reasoning |
+| `finance` | Finance | Invoices, P&L, budgeting, cash flow, tax estimates |
+| `marketing` | Marketing | Social media content, ad copy, SEO, campaign planning |
+| `inventory` | Supply Chain | Stock levels, reorder points, supplier management |
+| `customer` | Customer Success | Support drafts, onboarding sequences, churn analysis |
+| `developer` | Engineering | Code generation, API docs, bug triage, test writing |
+| `operations` | Operations | SOPs, process mapping, KPI dashboards, compliance |
+| `research` | Research | Market analysis, competitor intel, literature reviews |
 
-```bash
-npm login
-# from packages/sdk:
-npm run build
-npm publish --access public        # or --access restricted for a scoped/owned package
+Discover available capabilities at runtime:
+```ts
+const detail = await ql.agents.get("finance");
+console.log(detail.capabilities.map((c) => c.id));
 ```
 
-To install from a local tarball instead of publishing:
+---
 
-```bash
-cd packages/sdk && npm pack        # -> ql-agent-sdk-0.1.0.tgz
-npm install /absolute/path/to/ql-agent-sdk-0.1.0.tgz
-```
+## Environment Variables
+
+| Variable | Purpose |
+|----------|---------|
+| `QL_API_KEY` | Your API key (convention — the SDK reads it from the `apiKey` option, not env directly) |
+| `QL_BASE_URL` | Override the base URL (useful for staging/self-hosted) |
+
+---
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| `QLError: unauthorized` | Key is invalid, revoked, or expired | Generate a new key in your dashboard |
+| `QLError: forbidden` | Key scope doesn't cover the endpoint | Create a key with the required scope or `*` |
+| `QLError: not_found` (agent) | Typo in agent slug | Use `ql.agents.list()` to see valid IDs |
+| `QLError: network` | Can't reach the API | Check your network / base URL / firewall |
+| Task stuck in `"running"` | Server restarted mid-execution | Wait for stale recovery (≤5 min) or poll again later |
+| Stream produces no output | Model returned empty response | Check `reasoning` field or try a different agent |
+
+---
+
+## License
+
+MIT