Merge pull request #5 from NimbleBrainInc/docs/workspace-lifecycle-alignment

Align workspace + MCP docs with lifecycle refactor (PR #67)

Author: mgoldsborough

src/content/docs/api/authentication.mdx

@@ -270,7 +270,7 @@ The server always responds to `OPTIONS` preflight requests with:
 
 ```
 Access-Control-Allow-Methods: GET, POST, PATCH, DELETE, OPTIONS
-Access-Control-Allow-Headers: Content-Type, Authorization, Mcp-Session-Id, Last-Event-ID, Mcp-Protocol-Version
+Access-Control-Allow-Headers: Content-Type, Authorization, Mcp-Session-Id, Last-Event-ID, Mcp-Protocol-Version, X-Workspace-Id
 Access-Control-Expose-Headers: Mcp-Session-Id, Mcp-Protocol-Version
 ```
 

src/content/docs/api/bootstrap.mdx

@@ -7,10 +7,19 @@ import { Aside, Tabs, TabItem } from '@astrojs/starlight/components';
 
 The Bootstrap API returns everything a client needs to initialize: the authenticated user's identity, their workspaces, and the active workspace's shell configuration. The web UI calls this on page load.
 
+Bootstrap is the discovery endpoint — the one place the server picks a default workspace for the caller. Data endpoints (`/mcp`, `/v1/chat`, `/v1/tools/call`, `/v1/shell`, `/v1/events`) treat `X-Workspace-Id` as authoritative and reject requests that omit it. Same header name, different strictness by endpoint class.
+
 ## GET /v1/bootstrap
 
 Returns the current user, their workspaces with roles, and the shell configuration for the active workspace.
 
+**Request headers:**
+
+| Header | Required | Description |
+|---|---|---|
+| `Authorization` | Yes | `Bearer <token>` — see [Authentication](/api/authentication) |
+| `X-Workspace-Id` | No | **Soft hint.** If present and the user is a member of this workspace, it becomes `activeWorkspace` in the response. Otherwise ignored and the first membership is returned. Clients use this to restore a user's last-selected workspace from local storage. |
+
 **Response:**
 
 ```json
@@ -50,15 +59,16 @@ Returns the current user, their workspaces with roles, and the shell configurati
 |-------|------|-------------|
 | `user` | `object` | Authenticated user identity (id, name, email, role) |
 | `workspaces` | `array` | Workspaces the user belongs to, with their role in each |
-| `activeWorkspace` | `string` | ID of the currently active workspace |
+| `activeWorkspace` | `string` | ID of the currently active workspace. Always populated — the server enforces the invariant that every authenticated user has at least one workspace (provisioned at login, re-created on next login if externally deleted). |
 | `shell` | `object` | Shell configuration — sidebar placements, route endpoints |
 | `config` | `object` | Runtime configuration — model, iteration limits, token limits |
 
 **Error responses:**
 
-| Status | Condition |
-|--------|-----------|
-| 401 | Not authenticated |
+| Status | Error code | Condition |
+|--------|-----------|-----------|
+| 401 | — | Not authenticated |
+| 500 | `workspace_invariant_violation` | Authenticated user reached bootstrap with zero workspaces. Provisioning should have run at login; this indicates a broken identity-layer path rather than client misuse. |
 
 **Example:**
 

src/content/docs/api/mcp-endpoint.mdx

@@ -76,7 +76,7 @@ Every MCP request is scoped to a workspace. External clients identify the worksp
 
 Workspace IDs have the form `ws_<alphanumeric>` and can be copied from **Settings → Profile → MCP Connection** in the web UI.
 
-If the user belongs to multiple workspaces and no header is set, the server returns `400` with the message "Multiple workspaces available. Set X-Workspace-Id header to specify which workspace to use." Set the header on every client config — it removes ambiguity if the user is later added to more workspaces.
+If the header is missing, the server returns `400` with the message "Workspace required. Set the X-Workspace-Id header. The workspace ID is available from GET /v1/bootstrap or Settings → Profile → MCP Connection." — regardless of how many workspaces the user belongs to. The server does not pick a default on data endpoints.
 
 ## What's exposed
 

src/content/docs/api/overview.mdx

@@ -78,7 +78,7 @@ Every endpoint requires authentication unless noted otherwise.
 | `POST` | `/v1/chat/stream` | Yes | Streaming chat (SSE) |
 | `GET` | `/v1/apps/:name/resources/:path` | Yes | Fetch a UI resource |
 | `POST` | `/v1/tools/call` | Yes | Direct tool invocation |
-| `GET` | `/v1/shell` | Yes | Shell configuration (placements, endpoints) |
+| `GET` | `/v1/shell` | Yes | Shell configuration (placements, endpoints) — requires `X-Workspace-Id` |
 | `GET` | `/v1/files/:fileId` | Yes | Serve an uploaded file |
 | `GET` | `/v1/events` | Yes | Workspace SSE event stream |
 | `GET` | `/v1/auth/provider` | No | Auth adapter info (local, oidc, or dev) |

src/content/docs/apps/placements.mdx

@@ -135,22 +135,28 @@ The `size` field provides a hint to the slot renderer:
 
 The `PlacementRegistry` is an in-memory store that tracks all active placements. It is updated when bundles are installed or uninstalled.
 
-**Registration** — When a bundle starts, its placements are registered. If the bundle has explicit `placements`, they are used directly. If it only has `primaryView`, `registerLegacy()` converts it to a single `"main"` placement.
+Every entry is either **ambient** (no `wsId` — platform-provided views like Home, Conversations, Files, Settings; always present inside any workspace) or **workspace-scoped** (installed bundles, visible only to members of that workspace). The registry exposes a single read method, `forWorkspace(wsId)`, which returns ambient + scoped entries merged and sorted. There is deliberately no "return everything" accessor — in a multi-tenant host, no legitimate caller wants placements unrelated to a workspace.
 
-**Querying** — `forSlot(slot)` returns all entries matching the slot (including sub-slots), sorted by priority ascending.
+**Registration** — When a bundle starts, its placements are registered against the installing workspace's `wsId`. If the bundle has explicit `placements`, they are used directly. If it only has `primaryView`, `registerLegacy()` converts it to a single `"main"` placement.
 
-**Unregistration** — When a bundle is uninstalled, all its placements are removed.
+**Querying** — `forWorkspace(wsId)` returns ambient entries plus entries scoped to `wsId`, sorted by slot then priority (lower first).
+
+**Unregistration** — When a bundle is uninstalled, its placements for that workspace are removed. Other workspaces' entries for the same bundle are untouched.
 
 ```typescript
-// Register explicit placements
-registry.register("my-app", [
-  { slot: "sidebar", resourceUri: "ui://nav", priority: 50, label: "My App" },
-  { slot: "main", resourceUri: "ui://dashboard", route: "my-app" },
-]);
-
-// Query sidebar items (includes sidebar.* sub-slots)
-const items = registry.forSlot("sidebar");
-// → sorted by priority, includes sidebar, sidebar.conversations, etc.
+// Register explicit placements, scoped to a workspace
+registry.register(
+  "my-app",
+  [
+    { slot: "sidebar", resourceUri: "ui://nav", priority: 50, label: "My App" },
+    { slot: "main", resourceUri: "ui://dashboard", route: "my-app" },
+  ],
+  "ws_engineering",
+);
+
+// Read the merged ambient + workspace-scoped list
+const items = registry.forWorkspace("ws_engineering");
+// → sorted by slot then priority
 ```
 
 ## Example: sidebar + main view

src/content/docs/using/workspaces.mdx

@@ -91,11 +91,15 @@ The agent installs the bundle and registers its tools in the workspace's tool re
 
 ## Switching workspaces
 
-In the web UI, switch workspaces from the workspace selector in the sidebar. The API uses the `X-Workspace-Id` header or the `workspaceId` field in chat requests to target a specific workspace.
+In the web UI, switch workspaces from the workspace selector in the sidebar. Every API request to a workspace-scoped endpoint (`/mcp`, `/v1/chat`, `/v1/tools/call`, `/v1/shell`, `/v1/events`) must include an `X-Workspace-Id` header. Chat requests continuing an existing conversation inherit the workspace from `conversationId` — no alternative addressing scheme.
+
+<Aside type="note">
+NimbleBrain guarantees every authenticated user has at least one workspace. One is provisioned on first login and re-created on the next login if manually deleted. Client code can rely on this invariant — `activeWorkspace` from `/v1/bootstrap` is always a valid workspace ID.
+</Aside>
 
 ## Bootstrap
 
-When the web UI loads, it calls `GET /v1/bootstrap` to get the current user's identity, workspace list with roles, and the active workspace's configuration. This single call provides everything needed to render the shell.
+Clients that don't yet know a workspace ID call `GET /v1/bootstrap` — the one endpoint where the server picks a default. It returns the authenticated user's identity, the full workspace list with roles, and the active workspace's shell configuration. Clients may send `X-Workspace-Id` on bootstrap as a soft hint (e.g., restoring a user's last selection from local storage); the server honors it when it matches a membership and falls back to the first workspace otherwise.
 
 ## What's next