@stackbone/sdk 0.1.0-alpha.7 → 0.1.0

package/README.md

@@ -4,563 +4,368 @@
 [![Node](https://img.shields.io/badge/node-%3E%3D24-brightgreen.svg)](https://nodejs.org/)
 [![TypeScript](https://img.shields.io/badge/types-TypeScript-blue.svg)](https://www.typescriptlang.org/)
 
-Official TypeScript SDK for [Stackbone](https://stackbone.ai) — the marketplace and managed runtime for containerized AI agents. Stackbone provisions a Postgres branch, object storage, an LLM gateway and the rest of the platform primitives for every agent; this SDK is the in-container surface those agents call.
+Official TypeScript SDK for [Stackbone](https://stackbone.ai) — the marketplace and managed runtime for AI agents. You author a **workspace** of durable agents and workflows; Stackbone provisions a Postgres branch (Neon), object storage, an LLM gateway and the rest of the platform primitives for it, and this SDK is the in-workspace surface your code calls through the ambient `stackbone` client.
 
 > "You write the agent. We connect it to the world."
 
 ## Features
 
-- **Database** — Direct Postgres access through a lazy Drizzle ORM wrapper bound to the agent's connection string, with full type-safe queries, transactions, and `sql` template literals — Drizzle is re-exported via `@stackbone/sdk/db` so the agent's `package.json` only depends on `@stackbone/sdk`
+- **Ambient client** — `import { stackbone } from '@stackbone/sdk'` and reach every platform surface from inside any tool's `execute()` or any workflow step. No `createClient()`, no credential wiring — config is resolved lazily from the env the runtime injects
+- **Database** — Native Drizzle ORM over the agent's own Neon Postgres, with type-safe queries, transactions, `pgvector` and `tsvector`. Drizzle is re-exported via `@stackbone/sdk/db` so your `package.json` only depends on `@stackbone/sdk`
 - **Storage** — S3-compatible object storage (Cloudflare R2 in prod, MinIO in dev) with automatic per-agent key prefixing and signed URLs
-- **AI** — Wrapper around the official `openai` SDK pointed at OpenRouter, so 300+ chat, embedding and image models are reachable through a single OpenAI-compatible API
-- **RAG** — Document parsing, chunking and `pgvector`-backed retrieval through a flat, ceremony-free API
-- **Observability** — OpenTelemetry span processor + run-cost aggregator + per-run logger
-- **Approval** — Human-in-the-loop inbox: fire-and-forget approval requests, HMAC-signed decision callbacks, and an LLM tool wrapper that gates execution behind human review
-- **Secrets** — Read organization-encrypted secrets registered in the dashboard, no client-side cache so rotations propagate immediately
-- **Config** — Typed reads of dynamic per-agent configuration the user set in the dashboard
-- **Coming soon (types only)** — `queues` (cross-container HTTP push via the BullMQ job dispatcher), `memory` (mem0-backed long-term memory), `prompts` (managed prompts with `{{var}}` templates), `connections` (OAuth integrations) and `events` (org-wide event bus). Public types are exported from `@stackbone/sdk` today; the runtime is not wired yet, so there is no live `client.X` accessor.
-- **TypeScript-first** — Full type definitions and a uniform `Result<T>` envelope on every method (no thrown errors at the SDK boundary)
-- **Lazy initialization** — Modules and partner SDKs are constructed on first access, so env vars rotated by the control plane after the client is built are still picked up
+- **AI** — OpenAI-compatible client pointed at OpenRouter, so 300+ chat, embedding and image models are reachable through a single managed sub-key
+- **RAG** — Document ingest and hybrid (`pgvector` + `tsvector`) retrieval through a flat, ceremony-free API; tables are platform-provisioned
+- **Workflows** — Durable, replayable orchestration: start, wait on, and schedule workflows by name, and pause on human approval, via `@stackbone/sdk/workflow`
+- **Human-in-the-loop** — `requestApproval()` pauses a workflow durably until a person decides in the Studio inbox (or the timeout fires)
+- **Connectors** — Call a brokered third-party integration (Slack, Gmail, …) with `stackbone.connection(id)` — no token ever enters the container
+- **Config, secrets & prompts** — Typed reads of dynamic per-agent config, organization-encrypted secrets, and a versioned prompt catalog
+- **TypeScript-first** — Full type definitions and a uniform `Result<{ data, error }>` envelope on every method (the two exceptions throw — see below)
 
 ## Installation
 
-`@stackbone/sdk` is the SDK every published agent depends on. Inside the Stackbone monorepo it is available via the `@stackbone/sdk` workspace alias. From a generated agent project:
+`@stackbone/sdk` is the SDK every Stackbone workspace depends on. From a generated workspace:
 
 ```bash
-# Alpha (today)
-pnpm add @stackbone/sdk@alpha
-
-# Once we cut a stable release the unscoped tag will resolve to the latest
-# minor:
 pnpm add @stackbone/sdk
 ```
 
+`@stackbone/sdk` declares `eve` and `workflow` as **optional peer dependencies**. Install only the ones your workspace uses:
+
+```bash
+pnpm add eve                          # to author an agent (agent.ts / tools)
+pnpm add workflow                     # to author a workflow that pauses for approval
+pnpm add @ai-sdk/openai-compatible    # to bind the OpenRouter-compatible model in agent.ts
+```
+
+A tool-only agent that never imports `@stackbone/sdk/workflow` or `@stackbone/sdk/connect` never loads those peers, so `import { stackbone } from '@stackbone/sdk'` stays peer-free.
+
 > Requires Node.js 24 or newer (the runtime your agent container ships with). The SDK is server-only — it is not built for the browser.
 
-Need a copy-pasteable starting point? See the [`example/`](https://github.com/stackbone/stackbone/tree/main/libs/sdk/example) directory in the repository — one ESM and one CJS file showing the canonical agent shape (schema with `@stackbone/sdk/db`, the runtime-injected `ctx.client`, async handler).
+> Scaffold a workspace with the `stackbone` CLI (`stackbone init`, `stackbone add agent|workflow`). The dev loop, publishing and migrations are CLI concerns — see the Stackbone CLI docs.
+
+## What you build — a workspace
 
-## Quick Start
+A **workspace** is a project that contains **agents** and **workflows**, discovered **by convention from the files on disk**:
 
-### The Client
+```
+my-workspace/
+  agents/
+    support/
+      agent.yaml              ← per-agent manifest; name: must equal the folder basename
+      schema.ts               ← Drizzle tables for stackbone.database
+      agent/
+        agent.ts              ← model + build config (default export = defineStackboneAgent)
+        instructions.md       ← the system prompt
+        tools/
+          read_config.ts      ← one tool per file (default export = defineTool)
+          escalate.ts
+  workflows/
+    onboarding.workflow.ts    ← 'use workflow' fn + sibling inputSchema / outputSchema
+  config.schema.ts            ← optional: typed dynamic config (Zod)
+  stackbone.config.ts         ← OPTIONAL override of the convention scan
+```
 
-You don't construct the client. The runtime builds a single `StackboneClient` per process — wired from the env vars the platform injects at provisioning time — and hands it to every handler as `ctx.client`. Define your agent with `defineAgent` and destructure `client` (and `input`) off the invocation context:
+- Every `agents/<name>/agent.yaml` (whose `name:` equals the folder basename) is an **agent**.
+- Every `workflows/<name>.workflow.ts` (exporting `<camelCase(name)>Workflow`) is a **workflow**.
+- `stackbone.config.ts` is an **optional** override — most workspaces need none. When present, `defineWorkspace({ agents, workflows })` wins over the scan:
 
 ```ts
-import { defineAgent, z } from '@stackbone/sdk';
-
-export default defineAgent({
-  invoke: {
-    input: z.object({ email: z.string() }),
-    output: z.object({ id: z.number() }),
-    async run({ input, client }) {
-      const [row] = await client.database
-        .insert(leads)
-        .values({ email: input.email, status: 'new', score: 0 })
-        .returning();
-      return { id: row.id };
+// stackbone.config.ts — OPTIONAL; only when convention discovery isn't enough
+import { defineWorkspace } from '@stackbone/sdk';
+
+export default defineWorkspace({
+  agents: [{ name: 'support', dir: 'agents/support' }],
+  workflows: [
+    {
+      name: 'onboarding',
+      module: 'workflows/onboarding.workflow.ts',
+      export: 'onboardingWorkflow',
     },
-  },
+  ],
 });
 ```
 
-#### Escape hatch — `createClient()`
+### Authoring an eve agent
 
-`createClient()` is still exported for when you need a client **outside** a handler (a script, a test, a one-off task) or want to override config explicitly — useful for local development against the emulator or when running outside a Stackbone container. In normal agent code you never need it; reach for `ctx.client` instead.
+An agent is a durable [eve](https://eve.dev/docs/introduction) agent — a model + instructions + tools that hold a conversation across turns. The runtime serves it over a signed session API; you write no HTTP code and no Dockerfile.
 
 ```ts
-import { createClient } from '@stackbone/sdk';
-
-// Zero-arg: every option falls back to an injected env var.
-const stackbone = createClient();
-
-// Or pass overrides explicitly.
-const local = createClient({
-  agentJwt: process.env.STACKBONE_AGENT_JWT,
-  stackboneApiUrl: 'http://localhost:3000',
-  agentId: 'agent_local_dev',
-  openrouterKey: process.env.OPENROUTER_API_KEY,
+// agents/support/agent/agent.ts
+import { defineStackboneAgent } from '@stackbone/sdk/eve';
+
+// `defineStackboneAgent` wraps eve's `defineAgent` with the Stackbone defaults:
+// the managed OpenRouter model bridge (the org's sub-key is injected at runtime
+// as OPENROUTER_API_KEY), the context window eve uses to size compaction, and
+// the `externalDependencies` (`@stackbone/sdk` + `eve*`) that keep the agent on
+// ONE invocation context — inlining the SDK gives it a second copy of the SDK's
+// AsyncLocalStorage and per-run logs arrive with no run id. Publishing enforces
+// the externals, so the helper always injects them.
+export default defineStackboneAgent({
+  model: 'anthropic/claude-haiku-4.5',
 });
 ```
 
-### Database
+> Pass a built `LanguageModel` instead of a string to use another provider, and
+> add `modelContextWindowTokens` / `build` to override a default. The raw form —
+> `defineAgent` from **`eve`** (not `@stackbone/sdk`) with an explicit
+> `createOpenAICompatible` provider — still works if you want full control.
 
-`client.database` is a lazy [Drizzle ORM](https://orm.drizzle.team/) instance bound to the agent's Postgres connection (`STACKBONE_POSTGRES_URL`). The full Drizzle surface (`select`, `insert`, `update`, `delete`, `transaction`, `execute`, `query`, `sql\`\``) is exposed verbatim, and the column builders live behind the `@stackbone/sdk/db`subpath so the creator never has to install`drizzle-orm`, `drizzle-orm/pg-core`or`postgres` directly.
+The agent's name lives in `agents/<name>/agent.yaml` and must equal the folder basename; the system prompt is `agent/instructions.md`. A **tool** is one file under `agent/tools/`, default-exporting `defineTool` from `eve/tools` — its `execute()` is where you reach the ambient `stackbone` client:
 
 ```ts
-import { defineAgent, z } from '@stackbone/sdk';
-import { eq, integer, pgTable, text } from '@stackbone/sdk/db';
-
-// 1. Declare your tables — types flow end to end.
-const leads = pgTable('leads', {
-  id: integer('id').primaryKey(),
-  email: text('email').notNull(),
-  status: text('status').notNull(),
-  score: integer('score').notNull(),
-});
-
-export default defineAgent({
-  invoke: {
-    input: z.object({}),
-    output: z.object({}),
-    async run({ client }) {
-      // 2. Query — `data` is typed from the schema, no codegen needed.
-      const rows = await client.database
-        .select()
-        .from(leads)
-        .where(eq(leads.status, 'qualified'))
-        .limit(20);
-
-      // 3. Mutate.
-      await client.database
-        .insert(leads)
-        .values({ id: 1, email: 'jane@example.com', status: 'new', score: 0 });
-
-      await client.database.update(leads).set({ status: 'contacted' }).where(eq(leads.id, 1));
-
-      await client.database.delete(leads).where(eq(leads.id, 1));
-
-      return {};
-    },
+// agents/support/agent/tools/escalate.ts
+import { defineTool } from 'eve/tools';
+import { stackbone, z } from '@stackbone/sdk';
+import { escalations } from '../../schema';
+
+export default defineTool({
+  description: 'Escalate this lead to a human sales rep.',
+  inputSchema: z.object({
+    leadId: z.string().describe('CRM contact id'),
+    reason: z.string().describe('Short reason for the hand-off'),
+  }),
+  async execute({ leadId, reason }) {
+    await stackbone.database.insert(escalations).values({ leadId, reason });
+    return { leadId, tagged: 'needs-human' };
   },
 });
 ```
 
-The snippets below assume the `client` destructured off `ctx` inside a handler (`async run({ client }) { ... }`).
+### Authoring a durable workflow
 
-Interactive transactions yield a `tx` with the same Drizzle surface as `client.database`:
+A workflow is a plain async function marked `'use workflow'`, with its side-effects in helpers marked `'use step'`. Its public contract is **sibling `inputSchema` / `outputSchema` exports** — there is no `defineWorkflow` wrapper. Each `'use step'` is a checkpoint: it runs once, is persisted, and resumes from the last completed step after a crash, so keep every step **idempotent**.
 
 ```ts
-await client.database.transaction(async (tx) => {
-  await tx.insert(leads).values({ id: 2, email: 'b@x.com', status: 'new', score: 0 });
-  await tx.update(leads).set({ status: 'qualified' }).where(eq(leads.id, 2));
+// workflows/onboarding.workflow.ts
+import { stackbone, z } from '@stackbone/sdk';
+import { welcomes } from '../agents/support/schema';
+
+// THE contract — sibling exports the build harvests into the manifest + a validator.
+export const inputSchema = z.object({
+  userId: z.string(),
+  email: z.email(),
+  plan: z.enum(['free', 'pro', 'scale']),
+});
+export const outputSchema = z.object({
+  userId: z.string(),
+  tips: z.array(z.string()),
 });
-```
 
-For raw SQL, reach for the `sql` tag re-exported from `@stackbone/sdk/db`:
+export async function onboardingWorkflow(input: z.infer<typeof inputSchema>) {
+  'use workflow'; // cheap, deterministic glue — it replays on resume; do I/O in steps
 
-```ts
-import { sql } from '@stackbone/sdk/db';
+  const signup = await validateSignup(input);
+  const saved = await persistWelcome(signup.userId);
+  return saved;
+}
 
-const { rows } = await client.database.execute(sql`SELECT NOW()`);
+async function validateSignup(input: z.infer<typeof inputSchema>) {
+  'use step';
+  if (!input.email.includes('@')) throw new Error(`Invalid email: ${input.email}`);
+  return { userId: input.userId, plan: input.plan };
+}
+
+async function persistWelcome(userId: string) {
+  'use step'; // idempotent side effect on userId
+  await stackbone.database.insert(welcomes).values({ userId });
+  return { userId, tips: ['Connect your inbox', 'Invite a teammate'] };
+}
 ```
 
-> If `STACKBONE_POSTGRES_URL` is unset, the first call to `client.database` raises `database_not_configured` with a hint to run `stackbone dev`. Migrations are governed by the `stackbone db migrate *` CLI commands — `client.database` itself is just the runtime query surface.
+## The ambient `stackbone` client
 
-### Storage
+`import { stackbone } from '@stackbone/sdk'` — the single handle for every platform surface, reachable from any tool `execute()` or workflow step. It resolves config from the injected environment lazily on first use; there is no `createClient()` in normal code and you never pass connection strings.
 
-`client.storage` is bucket-scoped via `from(bucket)` and transparently prefixes every key with `${agentId}/${bucket}/` before talking to S3 / R2 / MinIO, so your agent code never has to think about multi-tenancy:
+| Surface                    | What it is                                                                           | Returns                                            |
+| -------------------------- | ------------------------------------------------------------------------------------ | -------------------------------------------------- |
+| `stackbone.database`       | **Native Drizzle ORM** over the agent's Neon (`pgvector`, `tsvector`)                | rows / **throws** (no `{ data, error }`)           |
+| `stackbone.storage`        | File uploads / downloads / signed URLs (R2 in prod, MinIO in dev)                    | `{ data, error }`                                  |
+| `stackbone.ai`             | LLM chat / embeddings / vision via OpenRouter (300+ models); stream long completions | `{ data, error }`                                  |
+| `stackbone.rag`            | Ingest + hybrid (`pgvector` + `tsvector`) retrieval; tables are platform-provisioned | `{ data, error }`                                  |
+| `stackbone.config`         | Read dynamic config the operator edits in Studio: `get(key)` / `getAll()`            | `{ data, error }`                                  |
+| `stackbone.secrets`        | Read operator-managed encrypted secrets: `get(name)` / `getMany(names)`              | `{ data, error }`                                  |
+| `stackbone.prompts`        | Versioned prompt catalog: `get()` / `compile(key, vars)` / `list()` / `create()`     | `{ data, error }`                                  |
+| `stackbone.agent(id)`      | Call a sibling agent by name — opens a session, sends a turn                         | `result()` → `{ data, status }`                    |
+| `stackbone.connection(id)` | Call a third-party connector by id (Stackbone Connect)                               | operation output / **throws** `ConnectorCallError` |
 
-```ts
-// Upload an object
-const { data, error } = await client.storage
-  .from('uploads')
-  .upload('reports/2026-04-29.pdf', pdfBlob, {
-    contentType: 'application/pdf',
-    metadata: { source: 'leads-agent' },
-  });
+The one rule across every surface: **destructure `{ data, error }` and handle both branches.** The only exceptions are `stackbone.database` (native Drizzle — returns rows, throws) and `stackbone.connection` (returns the operation output, throws `ConnectorCallError`).
 
-// Download an object (returns a Blob)
-const { data, error } = await client.storage.from('uploads').download('reports/2026-04-29.pdf');
+### Database
 
-// List objects (paginated)
-const { data, error } = await client.storage
-  .from('uploads')
-  .list({ prefix: 'reports/', limit: 50 });
+Native Drizzle — awaiting a query returns the typed rows and **throws** on error (handle with `try/catch` or let it bubble). Tables are `pgTable` objects from `agents/<name>/schema.ts`; the column builders and helpers (`eq`, `and`, `sql`, …) all come from `@stackbone/sdk/db`, so you never install `drizzle-orm` directly.
 
-// Delete an object
-const { data, error } = await client.storage.from('uploads').remove('reports/2026-04-29.pdf');
+```ts
+import { eq, desc } from '@stackbone/sdk/db';
+import { leads } from '../../schema';
+
+const rows = await stackbone.database
+  .select()
+  .from(leads)
+  .where(eq(leads.status, 'qualified'))
+  .orderBy(desc(leads.createdAt))
+  .limit(20); // a select() resolves to an ARRAY — const [first] = rows
+
+const [created] = await stackbone.database
+  .insert(leads)
+  .values({ email: 'jane@example.com', status: 'new', score: 0 })
+  .returning();
+
+await stackbone.database.transaction(async (tx) => {
+  await tx.update(leads).set({ status: 'contacted' }).where(eq(leads.id, created.id));
+});
 ```
 
-Signed URLs and a public URL helper are exposed for direct browser uploads / downloads:
+### Storage
+
+Bucket-scoped via `from(bucket)`; every key is transparently prefixed with the agent id so your code never thinks about multi-tenancy:
 
 ```ts
-// Pre-signed upload URL (1h by default; clamp the contentType into the signature)
-const { data: upload } = await client.storage
+const { data, error } = await stackbone.storage
   .from('uploads')
-  .getSignedUploadUrl('avatars/user-42.png', {
-    expiresIn: 600,
-    contentType: 'image/png',
-  });
+  .upload('reports/2026-04-29.pdf', pdfBlob, { contentType: 'application/pdf' });
+if (error) throw new Error(error.message);
 
-// Pre-signed download URL — prefer this over `download()` for large objects,
-// since `download()` materialises the entire body in memory as a Blob.
-const { data: download } = await client.storage
+// Prefer a signed URL over download() for large objects (download materialises the body).
+const { data: url } = await stackbone.storage
   .from('uploads')
   .getSignedDownloadUrl('reports/2026-04-29.pdf');
-
-// Canonical public URL (only fetchable for public buckets)
-const { data: url } = client.storage.from('uploads').getPublicUrl('avatars/user-42.png');
 ```
 
 ### AI
 
-`client.ai` mirrors the official `openai` SDK shape but every request is routed through OpenRouter, so you can pick from 300+ models with a single API key. The Stackbone platform attributes usage and billing back to the agent through OpenRouter Activity — no proxy in the middle.
+OpenAI-compatible shape, routed through OpenRouter (300+ models, one managed sub-key). The envelope covers the handshake; once a stream is open, mid-flight errors surface through the iterator (`try/catch` your `for await`).
 
 ```ts
-// Chat completion
-const { data, error } = await client.ai.chat.completions.create({
+const { data, error } = await stackbone.ai.chat.completions.create({
   model: 'anthropic/claude-sonnet-4.5',
-  messages: [
-    { role: 'system', content: 'You are a sales qualification assistant.' },
-    { role: 'user', content: 'Score this lead: ...' },
-  ],
+  messages: [{ role: 'user', content: 'Score this lead: ...' }],
 });
+if (!error) console.log(data.choices[0]?.message.content);
 
-if (!error) {
-  console.log(data.choices[0]?.message.content);
-}
-```
-
-Streaming uses the same method with `stream: true`. The `Result` envelope only covers the handshake — once the stream is open, mid-flight errors propagate through the iterator, so wrap your `for await` loop in `try/catch`:
-
-```ts
-const { data: stream, error } = await client.ai.chat.completions.create({
-  model: 'anthropic/claude-sonnet-4.5',
-  messages: [{ role: 'user', content: 'Stream me a haiku.' }],
-  stream: true,
-});
-
-if (!error) {
-  for await (const chunk of stream) {
-    process.stdout.write(chunk.choices[0]?.delta?.content ?? '');
-  }
-}
-```
-
-Embeddings, image generation and a model catalogue are first-class too:
-
-```ts
-// Embeddings — returns the standard OpenAI shape
-const { data, error } = await client.ai.embeddings.create({
+const { data: emb } = await stackbone.ai.embeddings.create({
   model: 'openai/text-embedding-3-small',
   input: 'A red Spanish sword from the 11th century.',
 });
-
-// Image generation — OpenRouter routes image models through chat completions;
-// the SDK normalises the response so callers see the OpenAI-shaped payload.
-// Returns `ai_no_image_generated` if the model produces zero images.
-const { data, error } = await client.ai.images.generate({
-  model: 'google/gemini-2.5-flash-image',
-  prompt: 'A medieval Spanish sword on a velvet cushion, museum lighting',
-});
-
-// List available models — preserves OpenRouter-specific fields like
-// `pricing`, `context_length`, `supported_parameters`, `architecture`
-const { data, error } = await client.ai.models.list();
-```
-
-Cancellation works the way you'd expect — pass an `AbortSignal` and aborts surface as `ai_aborted` on non-streaming calls:
-
-```ts
-const controller = new AbortController();
-setTimeout(() => controller.abort(), 5_000);
-
-const { data, error } = await client.ai.chat.completions.create(
-  { model: 'anthropic/claude-sonnet-4.5', messages: [...] },
-  { signal: controller.signal },
-);
 ```
 
 ### RAG
 
-`client.rag` exposes a flat, ceremony-free retrieval API on top of `pgvector` running in the agent's Postgres branch. There are no collections to create, no handles to thread through your code: the schema is auto-provisioned on the first `ingest()` and the embedding dimensions are inferred from the first chunk.
-
-The fast path lets the SDK handle embeddings for you — pass an embedding `model` and the chunks as plain strings, and `client.rag` calls `client.ai.embeddings.create` internally with batching:
-
-```ts
-// 1. Parse a document → plain text. Supports text/*, text/markdown and application/pdf.
-const text = await client.rag.parse(file);
-
-// 2. Split into chunks. Pure utility, no DB call.
-const chunks = client.rag.chunk(text, { size: 512, overlap: 64 });
-
-// 3. Ingest. The SDK embeds the chunks for you in batches of 128 and
-//    provisions the schema on the first call (HNSW + cosine, dims inferred
-//    from the first batch). Re-ingesting the same `id` atomically replaces
-//    all of that document's chunks.
-await client.rag.ingest({
-  id: 'doc-1',
-  chunks,
-  model: 'openai/text-embedding-3-small',
-  metadata: { source: 'manual-upload' },
-});
-
-// 4. Retrieve. Pass the user's question and the same model — the SDK embeds
-//    it for you and returns hits scored in [0, 1] (cosine similarity).
-const { data: hits } = await client.rag.retrieve({
-  text: 'how does X work?',
-  model: 'openai/text-embedding-3-small',
-  topK: 5,
-  filter: { source: 'manual-upload' },
-});
-```
-
-The escape hatch — pass embeddings precomputed yourself (different provider, custom dimensions, your own batching, deterministic offline tests):
+Flat ingest + hybrid retrieval over the platform-provisioned tables — no collections to create:
 
 ```ts
-const { data: embeddings } = await client.ai.embeddings.create({
-  model: 'openai/text-embedding-3-small',
-  input: chunks,
-});
-
-await client.rag.ingest({
-  id: 'doc-1',
-  chunks: chunks.map((content, i) => ({
-    content,
-    embedding: embeddings.data[i].embedding,
-  })),
-  metadata: { source: 'manual-upload' },
+await stackbone.rag.ingest({
+  collection: 'docs',
+  content: markdown,
+  contentType: 'text/markdown',
 });
 
-const { data: hits } = await client.rag.retrieve({
-  embedding: queryEmbedding,
+const { data: hits } = await stackbone.rag.search({
+  collection: 'docs',
+  query: 'how does X work?',
   topK: 5,
 });
 ```
 
-Delete by id (whole document) or by metadata predicate:
+> For durable ingest of large documents, prefer `ingestDocuments()` from `@stackbone/sdk/workflow` (runs the reserved `rag-ingest` workflow).
 
-```ts
-await client.rag.delete('doc-1');
-await client.rag.delete(['doc-1', 'doc-2']);
-
-await client.rag.deleteWhere({ source: 'manual-upload' });
-```
-
-Logical separation between document sets is via an optional `namespace` (default `'default'`). Backed by an indexed column in the same table — no extra physical collections to manage:
-
-```ts
-await client.rag.ingest({
-  id: 'faq-1',
-  chunks: [...],
-  namespace: 'faqs',
-});
-
-await client.rag.retrieve({ embedding, namespace: 'faqs' });
-await client.rag.deleteWhere({}, { namespace: 'faqs' });
-```
+### Config, secrets & prompts
 
-If you switch embedding models (e.g. `text-embedding-3-small` → `text-embedding-3-large`) the dimensions will not match what the table was provisioned with. The next `ingest()` returns `rag_dim_mismatch` with the exact stored vs received dims. Recreate the schema with:
+All three are `{ data, error }`, read-only, and key-checked. `config.schema.ts` (a Zod object at the workspace root) generates types so `stackbone.config.get('greeting')` is typed and a typo is a compile error.
 
 ```ts
-await client.rag.reset();
+const { data: tone } = await stackbone.config.get('replyTone'); // typed from config.schema.ts
+const { data: apiKey, error } = await stackbone.secrets.get('STRIPE_API_KEY');
+const { data: body } = await stackbone.prompts.compile('welcome-email', { name: 'Jane' });
 ```
 
-> `parse()` is intentionally minimal: passthrough for text and markdown, `unpdf` for text-only PDFs (no OCR, no layout reconstruction). For complex documents (scanned PDFs, Office files, multi-column layouts) the recommended path is to parse upstream of the SDK and pass the resulting text into `chunk()` directly.
+### Calling a sibling agent
 
-### Approval (Human-In-The-Loop)
-
-`client.approval` exposes a **fire-and-forget** primitive: the agent issues an approval request, the call returns immediately with the `approvalId` and a `callbackUrl`, and the control plane POSTs the human's decision to the endpoint the agent registered in `onDecide`. The callback is HMAC-signed (`Stackbone-Signature: t=<unix>,v1=<hex>`) so the agent can authenticate it without storing any per-approval secret.
-
-This shape decouples waiting from the container lifecycle — the agent does not have to keep a long-poll connection alive while a human reviews, which means it survives idle scale-to-zero and arbitrary numbers of concurrent approvals without tying up sockets.
-
-```ts
-// 1. Issue an approval — returns immediately, the human reviews asynchronously.
-const { data, error } = await client.airoval.request({
-  topic: 'lead.qualify',
-  payload: { leadId: 42, score: 0.6 },
-  title: 'Approve lead qualification',
-  description: 'Score is below the auto-qualify threshold (0.7).',
-  onDecide: '/approvals/lead-qualify',
-  timeout: '24h', // ISO duration or ms; default 24h
-  onTimeout: 'reject', // 'reject' | 'approve' | 'ignore'
-  approver: 'team:sales',
-  idempotencyKey: 'qualify-42',
-  metadata: { runId: 'r_123' },
-});
-// data: { approvalId, status: 'pending', callbackUrl, expiresAt }
-
-// 2. Receive the decision — `verify()` authenticates the inbound POST and
-//    returns a typed Decision<T>. Pass the raw `Request` (Fetch / Hono /
-//    undici) and switch on `decision.status`.
-app.post('/approvals/lead-qualify', async (c) => {
-  const result = await client.airoval.verify<{ leadId: number; score: number }>(c.req.raw);
-  if (result.error) return c.text('invalid', 401);
-  switch (result.data.status) {
-    case 'approved':
-      await processLead(result.data.payload);
-      break;
-    case 'rejected':
-      await archiveLead(result.data.payload);
-      break;
-    case 'timed_out':
-    case 'cancelled':
-      // No payload — only `decidedAt` (and an optional `reason` for cancelled).
-      break;
-  }
-  return c.json({ ok: true });
-});
-```
-
-Operations on existing approvals:
+From a workflow step (or another agent's tool), open a session and send a turn; the structured reply is validated against the `outputSchema` you pass:
 
 ```ts
-await client.airoval.cancel(approvalId, 'no longer needed');
-const { data: record } = await client.airoval.get<LeadPayload>(approvalId);
-const { data: page } = await client.airoval.list({
-  status: 'pending',
-  topic: 'lead.qualify',
-  limit: 50,
-});
-```
-
-#### Approval-gated LLM tools
-
-`client.airoval.tool()` wraps an LLM tool so the agent loop pauses for human review before `execute()` runs. When `needsApproval` returns `true`, `invoke()` opens an approval and returns a `pending` marker — the caller persists agent state and breaks the loop; the eventual decision callback (handled via `verify()`) is the signal to resume.
-
-```ts
-const sendInvoice = client.airoval.tool({
-  name: 'send_invoice',
-  description: 'Send an invoice to a recipient.',
-  parameters: {
-    type: 'object',
-    properties: {
-      amount: { type: 'number' },
-      recipient: { type: 'string' },
-    },
-    required: ['amount', 'recipient'],
-  },
-  needsApproval: ({ amount }) => amount > 1000,
-  toRequest: (input) => ({
-    onDecide: '/approvals/send-invoice',
-    title: `Send invoice for $${input.amount}`,
-    description: `Recipient: ${input.recipient}`,
-  }),
-  execute: async ({ amount, recipient }) => sendInvoiceImpl(amount, recipient),
-});
-
-// Pass the tool to chat.completions.create — it speaks the OpenAI shape.
-const completion = await client.ai.chat.completions.create({
-  model: 'anthropic/claude-sonnet-4.5',
-  messages,
-  tools: [sendInvoice.openaiSpec()],
-});
-
-// Drive the tool calls the LLM emitted.
-for (const call of completion.data?.choices[0]?.message.tool_calls ?? []) {
-  const r = await sendInvoice.invoke(JSON.parse(call.function.arguments));
-  if (r.error) return { error: r.error };
-  if (r.data.status === 'pending') {
-    // Approval was created. Persist agent state and break the loop —
-    // the decision callback will resume it.
-    return { pending: r.data.approvalId };
-  }
-  messages.push({
-    role: 'tool',
-    tool_call_id: call.id,
-    content: JSON.stringify(r.data.result),
+async function askSupportForTips(plan: string) {
+  'use step';
+  const session = stackbone.agent('support').session();
+  const response = await session.send<{ tips: string[] }>({
+    message: `A customer joined the "${plan}" plan. Give up to 3 onboarding tips.`,
+    outputSchema: z.object({ tips: z.array(z.string()) }),
   });
+  const result = await response.result(); // { data, status }
+  return result.data ?? { tips: [] };
 }
 ```
 
-The signing key for `verify()` is read from `STACKBONE_APPROVAL_SIGNING_KEY` (or `approvalSigningKey` on `createClient`). Timestamp tolerance defaults to 300 seconds; tighten or override per call with `verify(req, { toleranceSeconds: 60 })`.
+### Calling a connector
 
-### Secrets
-
-`client.secrets` reads organization-encrypted secrets the user registered in the dashboard. The SDK is **read-only** by design — secrets are managed in the control plane, never written from inside an agent container. There is no client-side cache: every `get()` is a network call so dashboard rotations propagate immediately.
+Run a brokered third-party operation directly — no agent, no model, no secret in the container. The call returns the operation output and **throws** a `ConnectorCallError` on failure (match `err.code`, never `instanceof`):
 
 ```ts
-// Single secret — `secrets_not_found` error if the name is not registered.
-const { data: apiKey, error } = await client.secrets.get('STRIPE_API_KEY');
-if (!error) {
-  const stripe = new Stripe(apiKey);
+async function sendMail(input: { to: string; subject: string; body: string }) {
+  'use step';
+  // Typed after `stackbone dev` generates .stackbone/connect.d.ts; equivalent to
+  // .call('sendMail', input). Use .call('chat.postMessage', args) for dotted ids.
+  return stackbone.connection('stub-mail').sendMail(input);
 }
-
-// Bulk read at boot — one round-trip; missing names come back as omissions.
-const { data: secrets } = await client.secrets.getMany(['STRIPE_API_KEY', 'SLACK_BOT_TOKEN']);
-// secrets: { STRIPE_API_KEY?: string; SLACK_BOT_TOKEN?: string }
-```
-
-### Config
-
-`client.config` reads dynamic per-agent configuration the user set in the dashboard (tone, thresholds, feature flags, prompts…). Like `secrets`, it is read-only and uncached — and the value is fully typed via the generic on `get`.
-
-```ts
-// Typed read — the generic narrows `data` to `'formal' | 'casual'`.
-const { data: tone } = await client.config.get<'formal' | 'casual'>('reply_tone');
-
-// Complex JSON — pass the full shape as the generic.
-interface Preferences {
-  tone: 'formal' | 'casual';
-  maxEmailsPerDay: number;
-}
-const { data: prefs } = await client.config.get<Preferences>('preferences');
-
-// Bulk read — typed via the second generic; missing keys come back as omissions.
-const { data: cfg } = await client.config.getMany<{
-  reply_tone: 'formal' | 'casual';
-  max_emails: number;
-}>(['reply_tone', 'max_emails']);
 ```
 
-`secrets.get` returns `secrets_not_found` (with the name in `meta`) when the secret is missing; `config.get` returns `config_not_found` symmetrically. Both `getMany` calls return whatever subset the organization has registered — no error for missing entries.
+## Subpath entrypoints
 
-### Memory (pending)
+Some surfaces ship behind subpaths so a tool-only agent never loads the `eve`/`workflow` peers it doesn't use:
 
-Long-term memory is a pending surface: its public types (`AddMemoryRequest`, `MemoryItem`, `MemoryHit`, `MemoryScope`, …) are exported from `@stackbone/sdk` so creators can type their integrations today, but there is no live `client.memory` accessor yet. The mem0-backed runtime will be added in a future release and promoted into the Features list above. See the [Coming Soon](#coming-soon) section for the full pending set.
+| Entrypoint                  | Key exports                                                                                                                                                                                                                                                  |
+| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `@stackbone/sdk/workflow`   | `requestApproval`, the raw `defineHook` / `sleep` escape hatch, `ingestDocuments` (the trigger/schedule helpers moved to `stackbone.workflows.*` on the main barrel; the loose `startWorkflow` / `scheduleWorkflow` / … exports here are deprecated aliases) |
+| `@stackbone/sdk/connect`    | `connect` (author an eve connection with brokered auth)                                                                                                                                                                                                      |
+| `@stackbone/sdk/db`         | Drizzle re-exports — column builders (`pgTable`, `text`, `vector`, …) and helpers (`eq`, `and`, `sql`, …)                                                                                                                                                    |
+| `@stackbone/sdk/db/testing` | `createTestDatabase` (spin up a throwaway Postgres for deterministic schema tests)                                                                                                                                                                           |
 
-### Coming Soon
+### Triggering & scheduling workflows
 
-The following surfaces have stable public **types** (so creators can write code against them today) but no runtime yet. They live under `src/surfaces/pending/` in the SDK source and do NOT appear as `client.X` accessors — importing the types directly from `@stackbone/sdk` is the supported path while the runtime is in flight:
+From inside a workflow, start or schedule another workflow **by name** through the ambient `stackbone.workflows` surface (these bind on dispatch, so call them from a workflow body or step, not a tool):
 
 ```ts
-import type {
-  PublishRequest,
-  AddMemoryRequest,
-  MemoryHit,
-  Prompt,
-  CreatePromptRequest,
-} from '@stackbone/sdk';
+import { stackbone } from '@stackbone/sdk';
+
+const { runId } = await stackbone.workflows.start('reconcile', { invoiceId }); // fire-and-forget → its own run
+const summary = await stackbone.workflows.startAndWait<Summary>('summarize', { docId }); // durably wait for the output
+await stackbone.workflows.schedule('daily-digest', { scope: 'all' }, '0 9 * * *'); // dynamic cron, idempotent by name
 ```
 
-The pending surfaces are `queues` (cross-container HTTP push), `memory` (mem0-backed long-term memory), `prompts` (managed prompts with `{{var}}` templates), `connections` (OAuth integrations) and `events` (organisation event bus). When their runtime lands they will be promoted into the live `client.X` set described in the Features section above.
+`name` is the `*.workflow.ts` convention name (narrowed to your declared workflows once `stackbone dev` generates `.stackbone/workflows.d.ts`); the input is validated against the target's `inputSchema` before anything is enqueued. There is no separate queue system — durable workflows _are_ the unit of background and scheduled work. For schedules that ship with the workspace, prefer the declarative `export const schedules = [{ cron, input }]` next to the workflow. (The loose `startWorkflow` / `startWorkflowAndWait` / `scheduleWorkflow` / `unschedule` / `listSchedules` exports on `@stackbone/sdk/workflow` still work but are deprecated aliases of these `stackbone.workflows.*` members.)
 
-## Configuration
+### Human-in-the-loop — `requestApproval`
 
-The runtime-injected `ctx.client` is already configured from the env vars the platform injects, so agent code rarely touches these fields. They matter when you reach for the `createClient()` escape hatch: `createClient` accepts a single configuration object where every field is optional and falls back to an environment variable, which the platform injects into the agent container at boot:
+A workflow that needs a person to decide pauses **durably** with `requestApproval()` from `@stackbone/sdk/workflow`. It writes a row the Studio inbox shows, then races the human decision against a timeout. **Call it from the workflow body, never inside a `'use step'`** — the pause is a workflow primitive that suspends the run.
 
 ```ts
-const stackbone = createClient({
-  // Ed25519 JWT signed by the control plane                → STACKBONE_AGENT_JWT
-  agentJwt: '...',
-  // Stackbone control plane base URL (used by facades)        → STACKBONE_API_URL
-  stackboneApiUrl: 'https://api.stackbone.ai',
-  // Stable agent identifier used as storage key prefix     → STACKBONE_AGENT_ID
-  agentId: 'agent_abc123',
-  // Postgres connection string for `client.database`, `client.rag` and the
-  // observability exporter                                  → STACKBONE_POSTGRES_URL
-  databaseUrl: 'postgresql://...',
-  // OpenRouter credentials                                  → OPENROUTER_API_KEY / OPENROUTER_BASE_URL
-  openrouterKey: '...',
-  openrouterBaseUrl: 'https://openrouter.ai/api/v1',
-  // RAG document parser                                     → LLAMA_PARSE_API_KEY
-  llamaParseApiKey: '...',
-  // mem0 credentials (memory module)                        → MEM0_API_KEY / MEM0_BASE_URL
-  mem0ApiKey: '...',
-  mem0BaseUrl: 'https://api.mem0.ai',
-  // HMAC key for verifying approval-decision callbacks       → STACKBONE_APPROVAL_SIGNING_KEY
-  approvalSigningKey: '...',
-  // Object storage credentials                              → STACKBONE_S3_ACCESS_KEY / STACKBONE_S3_SECRET_KEY / STACKBONE_S3_ENDPOINT / STACKBONE_S3_BUCKET / STACKBONE_S3_REGION
-  s3: {
-    accessKeyId: '...',
-    secretAccessKey: '...',
-    endpoint: 'https://<account>.r2.cloudflarestorage.com',
-    bucket: 'stackbone-prod',
-    region: 'auto',
-  },
-  // OpenTelemetry exporter
-  otel: {
-    exporterOtlpEndpoint: 'https://otel.stackbone.ai',
-    resourceAttributes: 'service.name=my-agent',
-  },
-});
+import { requestApproval } from '@stackbone/sdk/workflow';
+
+export async function refundWorkflow(input: z.infer<typeof inputSchema>) {
+  'use workflow';
+
+  const decision = await requestApproval({
+    token: `refund-${input.orderId}`, // resume key — unique per approval in the run
+    topic: 'refund',
+    payload: { orderId: input.orderId, amount: input.amount },
+    title: 'Approve refund',
+    timeout: '24h', // ISO-8601 duration or ms
+    fallback: 'reject', // applied if the timeout wins the race
+  });
+
+  // status === 'approved' is the ONLY green light; gate the side-effect on it.
+  if (decision.status !== 'approved') {
+    return { orderId: input.orderId, refunded: false, decision: decision.status };
+  }
+  await performRefund(input.orderId, input.amount); // a non-idempotent step, gated
+  return { orderId: input.orderId, refunded: true, decision: decision.status };
+}
 ```
 
-Inside a Stackbone-hosted container all of these are pre-populated, so production agent code just reads `ctx.client` (a zero-arg `createClient()` would resolve the same values). For local development the `stackbone dev` emulator wires up the same env vars against MinIO, a local Postgres branch and your own OpenRouter key.
+`requestApproval` resolves to `{ status: 'approved' | 'rejected', payload?, timedOut }` — `timedOut` is `true` only when the `fallback` fired. A human resolves it from the Studio inbox or the `stackbone hitl` CLI.
 
 ## Result Envelope and Error Handling
 
-Every SDK method returns the same discriminated union:
+Every SDK method (except `stackbone.database` and `stackbone.connection`, which throw) returns the same discriminated union:
 
 ```ts
 type Result<T> = { data: T; error: null } | { data: null; error: SdkError };
@@ -576,45 +381,39 @@ interface SdkError {
 Narrowing on `error` automatically refines `data` to `T`, so the typical caller looks like:
 
 ```ts
-const result = await client.ai.chat.completions.create({ model, messages });
+const result = await stackbone.ai.chat.completions.create({ model, messages });
 
 if (result.error) {
   console.error(`[${result.error.code}] ${result.error.message}`, result.error.meta);
-  return;
+  return; // or: throw new Error(result.error.message) to propagate
 }
 
 console.log(result.data.choices[0]?.message.content);
 ```
 
-Each module ships its own stable code prefix so you can pattern-match without parsing the message:
-
-| Prefix            | Source                                                          | Examples                                                                                                                                                                                                                                                                                                 |
-| ----------------- | --------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `ai_*`            | `client.ai`                                                     | `ai_unauthorized`, `ai_credits_exhausted`, `ai_rate_limited`, `ai_aborted`, `ai_no_image_generated`                                                                                                                                                                                                      |
-| `s3_*`            | `client.storage`                                                | `s3_credentials_missing`, `s3_invalid_key`, `s3_error`                                                                                                                                                                                                                                                   |
-| `rag_*`           | `client.rag`                                                    | `rag_invalid_request`, `rag_dim_mismatch`, `rag_embedding_failed`, `rag_error`                                                                                                                                                                                                                           |
-| `approval_*`      | `client.approval`                                               | `approval_invalid_request`, `approval_invalid_signature`, `approval_signature_expired`, `approval_signing_key_missing`, `approval_invalid_payload`, `approval_tool_execute_failed`, `approval_unauthorized`, `approval_forbidden`, `approval_not_found`, `approval_rate_limited`, `approval_unavailable` |
-| `secrets_*`       | `client.secrets`                                                | `secrets_invalid_request`, `secrets_not_found`, `secrets_invalid_response`, `secrets_unauthorized`, `secrets_forbidden`, `secrets_rate_limited`, `secrets_unavailable`                                                                                                                                   |
-| `config_*`        | `client.config`                                                 | `config_invalid_request`, `config_not_found`, `config_invalid_response`, `config_unauthorized`, `config_forbidden`, `config_rate_limited`, `config_unavailable`                                                                                                                                          |
-| `memory_*`        | `client.memory`                                                 | reserved for the future mem0-backed implementation; today every method returns `not_implemented`                                                                                                                                                                                                         |
-| `http_*`          | transport-level errors                                          | `http_timeout`, `http_aborted`, `http_network_error`, `http_parse_error`, `http_request_failed` — surface-level statuses (401/403/404/429/5xx) remap to `<surface>_*` codes                                                                                                                              |
-| `database_*`      | `client.database`                                               | `database_not_configured` (raised when `STACKBONE_POSTGRES_URL` is unset)                                                                                                                                                                                                                                |
-| `observability_*` | run-cost rollup (`@stackbone/sdk/observability`, runtime-wired) | `observability_close_run_failed`                                                                                                                                                                                                                                                                         |
-| `contract_*`      | gated surfaces                                                  | `contract_malformed`, `contract_unreachable`, `contract_version_unsupported` — emitted by any gated call when the contract handshake fails                                                                                                                                                               |
-| `capability_*`    | gated surfaces                                                  | `capability_unavailable` — emitted when the negotiated contract advertises no support for the surface                                                                                                                                                                                                    |
-| `*_missing`       | configuration                                                   | `agent_id_missing`, `openrouter_key_missing`, `database_url_missing`, `stackbone_api_url_missing`                                                                                                                                                                                                        |
-| `not_implemented` | stubbed module surface                                          | returned by every "coming soon" method until it ships                                                                                                                                                                                                                                                    |
-
-> The canonical inventory of every code lives in `src/errors/codes.ts` as a typed catalog (`SdkErrorCode`). The table above is the human-readable summary; adding or removing a code is a single-file edit there and the compiler refuses any literal `code` value not declared in the catalog. Pattern-match against `SdkErrorCode` (exported from `@stackbone/sdk`) for full type narrowing, or call `isSdkErrorCode(raw)` to widen a wire string back into the catalog.
+`throw` to propagate a failure; branch on `error.code` to handle a known case and `return` instead. **Never swallow the `error` branch.** Each surface ships its own stable code prefix so you can pattern-match without parsing the message:
+
+| Prefix       | Source               | Examples                                                                                            |
+| ------------ | -------------------- | --------------------------------------------------------------------------------------------------- |
+| `ai_*`       | `stackbone.ai`       | `ai_unauthorized`, `ai_credits_exhausted`, `ai_rate_limited`, `ai_aborted`                          |
+| `s3_*`       | `stackbone.storage`  | `s3_credentials_missing`, `s3_invalid_key`, `s3_error`                                              |
+| `rag_*`      | `stackbone.rag`      | `rag_invalid_request`, `rag_dim_mismatch`, `rag_embedding_failed`, `rag_error`                      |
+| `approval_*` | `stackbone.approval` | `approval_invalid_request`, `approval_persist_failed`, `approval_not_found`, `approval_unavailable` |
+| `secrets_*`  | `stackbone.secrets`  | `secrets_invalid_request`, `secrets_not_found`, `secrets_unavailable`                               |
+| `config_*`   | `stackbone.config`   | `config_invalid_request`, `config_not_found`, `config_unavailable`                                  |
+| `prompts_*`  | `stackbone.prompts`  | `prompts_not_found`, `prompts_invalid_request`, `prompts_unavailable`                               |
+| `http_*`     | transport-level      | `http_timeout`, `http_aborted`, `http_network_error` — surface statuses remap to `<surface>_*`      |
+
+`stackbone.database` throws Postgres/Drizzle errors (no envelope); `stackbone.connection` throws a `ConnectorCallError` whose `err.code` follows the broker taxonomy (`invalid_args`, `credential_error`, `timeout`, `ambiguous`, `unauthorized`, `unavailable`).
+
+> The canonical inventory of every envelope code lives in `src/errors/codes.ts` as a typed catalog (`SdkErrorCode`, exported from `@stackbone/sdk`). The compiler refuses any literal `code` not declared there; call `isSdkErrorCode(raw)` to widen a wire string back into the catalog.
 
 ## TypeScript Support
 
-The SDK is written in TypeScript and ships its own type definitions:
+The SDK is written in TypeScript and ships its own type definitions. The ambient client, the `Result<T>` envelope and the surface types are all typed end to end:
 
 ```ts
-import { createClient, StackboneClient, type Result, type SdkError } from '@stackbone/sdk';
-
-const stackbone: StackboneClient = createClient();
+import { stackbone, z, type Result, type SdkError } from '@stackbone/sdk';
 
 const result = await stackbone.ai.chat.completions.create({
   model: 'anthropic/claude-sonnet-4.5',
@@ -622,28 +421,19 @@ const result = await stackbone.ai.chat.completions.create({
 });
 ```
 
-Chat, embeddings and streaming types are re-exported directly from the `openai` package — by design, an agent author who already knows the OpenAI SDK does not have to relearn anything.
-
-For typed queue payloads, augment the `QueueJobs` registry once and both publisher and consumer pick up the shape:
+Chat, embeddings and streaming types are re-exported directly from the OpenAI-compatible layer — an author who already knows the OpenAI SDK does not have to relearn anything. `stackbone.config.get(...)`, the workflow trigger names, and `stackbone.connection(id).<operation>` all narrow to your own workspace once `stackbone dev` has generated the `.stackbone/*.d.ts` ambient types.
 
-```ts
-declare module '@stackbone/sdk/queues/types' {
-  interface QueueJobs {
-    'lead.qualified': { leadId: number; score: number };
-    'send-report': { reportId: string; recipient: string };
-  }
-}
-```
+> **Advanced escape hatch.** A `createClient()` is still exported for code that runs **outside** a tool/step (a script, a test, a one-off) or that must override config explicitly. In normal workspace code you never need it — reach for the ambient `stackbone` instead.
 
 ## Runtime
 
-The SDK targets Node.js 24+ inside the agent container. It is not designed for browser bundles — direct database access, S3 SDK usage and the agent JWT all assume a server-side runtime. For browser-side flows (uploads, public asset access), use the signed URLs returned by `client.storage` and let the browser hit S3 directly.
+The SDK targets Node.js 24+ inside the agent container. It is not designed for browser bundles — direct database access, S3 SDK usage and the signed runtime calls all assume a server-side runtime. For browser-side flows (uploads, public asset access), use the signed URLs returned by `stackbone.storage` and let the browser hit S3 directly. Observability needs no configuration: the runtime auto-instruments outbound calls and correlates `console.*` output with the right run.
 
 ## Documentation
 
 - **[Stackbone TECH_STACK](../../docs/TECH_STACK.md)** — Normative stack and platform primitives
-- **[ADR — SDK monolítico del agente](../../docs/arquitectura/decisiones/2026-04-24-sdk-monolitico-agente.md)** — Why a single SDK, scope of every module, error model
-- **[Componente — SDK & Creator DX](../../docs/arquitectura/componentes/04-sdk-creator-dx.md)** — End-to-end developer experience for agent creators
+- **[ADR — SDK monolítico del agente](../../docs/arquitectura/decisiones/2026-04-24-sdk-monolitico-agente.md)** — Why a single SDK, scope of every surface, error model
+- **[Componente — SDK & Creator DX](../../docs/arquitectura/componentes/04-sdk-creator-dx.md)** — End-to-end developer experience for creators
 
 ## License