Publish the TypeScript SDK and integration guides (#3141)

* feat(client): publish the TypeScript SDK surface

Make the high-level client API usable for external integrations and document complete agent, workspace, provider, event, and recipe flows.

* fix(client): correlate provider snapshots by daemon cwd

Return the daemon's canonical snapshot identity so waitForReady can match updates for relative, tilde, and otherwise non-canonical paths without duplicating filesystem rules in the SDK.

* test(server): make snapshot cwd assertion portable

* fix(client): gate canonical provider snapshot waits

Older daemons do not expose the canonical snapshot identity needed to correlate workspace updates safely. Require the advertised capability and fail with an update-host message instead of guessing across workspaces.

public-docs/sdk/workspaces.md

@@ -0,0 +1,114 @@
+---
+title: Workspaces with the SDK
+description: Open directories as Paseo workspaces, place agents in them, follow changes, and archive them.
+nav: Workspaces
+order: 53
+category: TypeScript SDK
+---
+
+# Workspaces with the SDK
+
+Use a workspace when an integration needs a durable place in the Paseo app for agents, terminals, browsers, and files related to one task.
+
+## Open a directory
+
+```ts
+const workspace = await client.workspaces.open("/Users/me/dev/storefront");
+
+console.log(workspace.id);
+console.log(workspace.directory);
+```
+
+`open()` creates the project when needed and reuses the active workspace for that exact directory. Use it when the directory is the identity you care about.
+
+## Create a fresh workspace
+
+`create()` always creates a new workspace, even when another workspace already uses the directory:
+
+```ts
+const workspace = await client.workspaces.create({
+  source: {
+    kind: "directory",
+    path: "/Users/me/dev/storefront",
+  },
+  title: "Checkout issue 42",
+});
+```
+
+Create a Paseo-owned worktree when concurrent work needs an isolated checkout:
+
+```ts
+const workspace = await client.workspaces.create({
+  source: {
+    kind: "worktree",
+    cwd: "/Users/me/dev/storefront",
+    action: "branch-off",
+    refName: "main",
+    branchName: "fix/checkout-42",
+  },
+  title: "Checkout issue 42",
+});
+```
+
+You can pass `projectId` in either source when you already have one. Most integrations should omit it; the daemon finds or creates the project from the directory.
+
+## Start an agent in a workspace
+
+Create through the workspace handle:
+
+```ts
+const agent = await workspace.agents.create({
+  config: {
+    provider: "claude/claude-sonnet-5",
+  },
+  prompt: "Map the checkout flow before changing anything.",
+});
+```
+
+The handle supplies both the workspace identity and its actual directory. This avoids mismatched placement arguments.
+
+For a one-off agent, you can skip the workspace call:
+
+```ts
+const agent = await client.agents.create({
+  config: {
+    provider: "claude/claude-sonnet-5",
+  },
+  cwd: "/Users/me/dev/storefront",
+  prompt: "Map the checkout flow before changing anything.",
+});
+```
+
+The daemon still creates a project and a fresh workspace. Read `agent.workspaceId` when you need the generated workspace ID.
+
+## List workspaces
+
+```ts
+let cursor: string | undefined;
+
+do {
+  const page = await client.workspaces.list({
+    filter: { query: "storefront" },
+    page: { limit: 50, cursor },
+  });
+
+  for (const workspace of page.entries) {
+    console.log(workspace.id, workspace.name, workspace.status);
+  }
+
+  cursor = page.pageInfo.nextCursor ?? undefined;
+} while (cursor);
+```
+
+## Refresh and archive a handle
+
+```ts
+const workspace = client.workspaces.ref(savedWorkspaceId);
+const snapshot = await workspace.refresh();
+
+if (snapshot) {
+  await workspace.archive();
+}
+```
+
+Workspace archive is separate from agent archive. Archive each resource according to the lifecycle your integration owns.