@cosmoops/connect-sdk 0.7.0 → 0.15.0

package/README.md

@@ -1,9 +1,15 @@
 # @cosmoops/connect-sdk
 
-Official client for the **CosmoOps Connect service-partner API** (`/api/v1/service/*`).
+Official client for the **CosmoOps Connect application-partner API** (`/api/v1/application/*`).
+
+**Current version: `0.8.0`** · [Release notes](#release-notes) · [Full changelog](./CHANGELOG.md)
+— follows semver with the 0.x convention that a **minor** version may carry a
+breaking change (a patch never does). Read the release notes for your target
+version before upgrading past a minor bump.
 
 ```bash
 npm install @cosmoops/connect-sdk
+npm install streamdown   # optional — Ask AI's markdown renderer, see step 4
 ```
 
 Two entry points, and the split is a security boundary, not a preference:
@@ -23,9 +29,114 @@ Browser  ──►  your backend  ──►  Connect
 (client)      (createConnectHandler + server client, holds the key)
 ```
 
+## Quickstart (Next.js)
+
+The fast path — most integrations are this and nothing else. Not on Next.js?
+Skip to [Other frameworks](#other-frameworks); the shape is the same, you
+just wire the session cookie yourself.
+
+**1. Install and get credentials.** From your application's Connect client section
+in Connect, copy the API key and OAuth client id.
+
+```bash
+npm install @cosmoops/connect-sdk
+```
+
+**2. Set environment variables.**
+
+| Variable | Required | Purpose |
+| --- | --- | --- |
+| `CONNECT_API_KEY` | yes | server-side credential |
+| `CONNECT_CLIENT_ID` | yes | OAuth client id |
+| `CONNECT_APP_URL` | no | non-production Connect instance |
+| `CONNECT_SESSION_COOKIE` | no | session cookie name |
+
+**3. Mount the bridge route.** One file, no arguments — this is your entire backend integration:
+
+```ts
+// app/api/connect/[...connect]/route.ts
+export { GET, POST } from "@cosmoops/connect-sdk/next";
+```
+
+**4. Wrap your layout and import the theme.**
+
+```tsx
+// app/layout.tsx
+import { ConnectProvider } from "@cosmoops/connect-sdk/client";
+
+<ConnectProvider>{children}</ConnectProvider>
+```
+
+```css
+/* app/globals.css */
+@import "tailwindcss";
+@import "@heroui/styles";
+@import "@cosmoops/connect-sdk/theme.css";
+
+/* Ask AI's markdown renderer. Tailwind skips node_modules unless told, and
+   Streamdown's utility classes live inside its compiled bundle. Adjust the
+   `../` count to reach your own node_modules. */
+@source "../node_modules/streamdown/dist/*.js";
+```
+
+```tsx
+// app/layout.tsx — Streamdown's streaming animation keyframes
+import "streamdown/styles.css";
+```
+
+Skip the last two if you pass `askAi={false}` to `AppShell`. The colour tokens
+Streamdown expects are already mapped onto HeroUI's in `theme.css`.
+
+**5. Register the redirect URI.** In the application's Connect client section, add
+`{your origin}/api/connect/callback`. This is the one step the SDK cannot do
+for you.
+
+**6. Read the session wherever you need it.**
+
+```tsx
+// app/dashboard/page.tsx
+import { requireConnectSession } from "@cosmoops/connect-sdk/next";
+
+export default async function DashboardPage() {
+  const session = await requireConnectSession(); // UserResponse — redirects if signed out
+  return <h1>{session.user.workspaceName}</h1>;
+}
+```
+
+**7. Verify the wiring.**
+
+```bash
+npx @cosmoops/connect-sdk doctor
+```
+
+That's the whole round trip — `/signin`, `/callback`, an httpOnly session
+cookie, `/session`, `/entitlements`, `/plans`, `/addons`, `/apps`,
+`/sessions`, `/logout` — with no `next.config.ts` changes, including
+`transpilePackages`: `dist/` is already ES2022 with `"use client"` hoisted,
+so Turbopack and webpack both consume it as-is.
+
+`npx @cosmoops/connect-sdk init` writes step 3's route file for you, plus a
+`/plans` page and an `.env.local` template for step 2 — then prints steps 4
+and 5 as the ones it won't do on your behalf, since those touch your own
+layout and Connect's dashboard rather than files it can safely write. See
+[Scaffolding](#scaffolding) below.
+
+Two things most integrations add next:
+
+- **A shell** — `AppShell` from `/client` is the rail and the access
+  gate every application platform needs. See [App shell](#app-shell).
+- **Route protection before render** — see [Route protection and
+  `proxy.ts`](#route-protection-and-proxyts) below; `requireConnectSession()`
+  above already redirects a signed-out visitor, so you only need this for
+  visitors you want bounced *before* a page starts rendering.
+
+The sections below this point cover the manual path — rolling the OAuth round
+trip yourself for a non-Next backend, or understanding what `/next` is doing
+for you under the hood.
+
 ## Server setup
 
-One credential does three jobs — the API key plaintext from your service's Integration tab is also your OAuth2 `client_secret` and the key your `id_token` is signed with. Revoking it revokes all three.
+One credential does three jobs — the API key plaintext from your application's Connect client section is also your OAuth2 `client_secret` and the key your `id_token` is signed with. Revoking it revokes all three.
 
 ```ts
 import { ConnectClient } from "@cosmoops/connect-sdk/server";
@@ -81,6 +192,49 @@ const { user, serviceRole } = await connect.identity.getUser(sessionToken);
 if (!serviceRole.granted.includes("invoice:write")) return forbidden();
 ```
 
+## Know which kind of account signed in
+
+`user.workspaceType` is `"individual"` (a one-seat personal account) or
+`"business"` (a team). It is the one fact about the workspace you cannot look
+up yourself — this API has no workspace read — and it decides whether half
+your UI is real: an individual workspace has exactly one seat and can never
+gain another, so a members table, an invite button and a seat meter can only
+ever fail there.
+
+`audience` answers the other half — what Connect's catalogue says your
+application is *sold* to, and whether this account qualifies:
+
+```ts
+const { user, audience } = await connect.identity.getUser(sessionToken);
+
+user.workspaceType;    // "individual"
+audience.application;  // "b2b"
+audience.matches;      // false — readiness will block, subscribing is refused
+```
+
+Both ship together so the check stays `!audience.matches` rather than a
+hardcoded audience constant in your own code that goes stale the moment an
+operator changes the catalogue entry. `audience.enforcedAtSignIn` says whether
+Connect refuses the hand-off itself; when it does, a mismatch only ever reaches
+you on a session minted before that setting was turned on.
+
+A mismatch is not a reason to sign anyone out. They have a valid Connect
+account — just the wrong kind of one for this application. `<ConnectAccessGate>`
+already blocks the shell on it.
+
+In the browser, the same two facts are `useConnectWorkspaceType()` and
+`useConnectAudience()`, and `<ConnectWorkspaceTypeGate>` is the declarative form:
+
+```tsx
+<ConnectWorkspaceTypeGate type="business">
+  <TeamMembersTable />
+</ConnectWorkspaceTypeGate>
+```
+
+That gate varies what each account type sees *inside* an application both
+audiences can reach. It is not the audience gate and does not replace
+`<ConnectAccessGate>`.
+
 **4. On logout.**
 
 ```ts
@@ -135,14 +289,14 @@ default: worth it for an app shell, less so for a marketing page.
 ```ts
 import { blockingBlockers } from "@cosmoops/connect-sdk";  // isomorphic
 
-const readiness = await connect.entitlements.getReadiness(orgId);
+const readiness = await connect.entitlements.getReadiness(workspaceId);
 
 if (!readiness.ready) {
   const [blocker] = blockingBlockers(readiness);
   return showBlocked(blocker.message, blocker.resolveUrl); // resolveUrl links into Connect
 }
 
-if (await connect.entitlements.hasFeature(orgId, "campaign-module")) {
+if (await connect.entitlements.hasFeature(workspaceId, "campaign-module")) {
   // ...
 }
 ```
@@ -153,7 +307,7 @@ Branch on `blocker.code`, never on `message`. Treat an unrecognised code as bloc
 
 ```ts
 const { balance } = await connect.billing.consumeAddon({
-  organizationId: orgId,
+  workspaceId,
   addonId: "api-calls",
   quantity: 1,
 });
@@ -204,7 +358,7 @@ await client.logs.write({
 });
 ```
 
-Both scopes on the stored entry come from something verified, never from your payload: `serviceId` from your API key, and `userId` from this token — which Connect checks is unrevoked, unexpired, and **minted for your service** before attributing anything. **There is no `userId` field to send.** An actor a caller can type is not an actor worth recording, and a conformance test fails the build if one ever appears in the server schema.
+Both scopes on the stored entry come from something verified, never from your payload: `applicationId` from your API key, and `userId` from this token — which Connect checks is unrevoked, unexpired, and **minted for your application** before attributing anything. **There is no `userId` field to send.** An actor a caller can type is not an actor worth recording, and a conformance test fails the build if one ever appears in the server schema.
 
 `write` returns `{ delivered, attributed }` and never throws. `attributed: false` with `delivered: true` means the token had expired (~15 days) or been revoked and the line was stored *without* a user — deliberately kept rather than rejected, because losing telemetry over a failed attribution is the worse of the two outcomes.
 
@@ -221,73 +375,20 @@ new ConnectClient({
 });
 ```
 
-## Next.js — plug and play
-
-Two files, no arguments.
-
-```ts
-// app/api/connect/[...connect]/route.ts
-export { GET, POST } from "@cosmoops/connect-sdk/next";
-```
-
-```tsx
-// app/layout.tsx
-import { ConnectProvider } from "@cosmoops/connect-sdk/client";
-
-<ConnectProvider>{children}</ConnectProvider>
-```
-
-```css
-/* app/globals.css */
-@import "tailwindcss";
-@import "@heroui/styles";
-@import "@cosmoops/connect-sdk/theme.css";
-```
-
-`npx @cosmoops/connect-sdk init` writes the route file and a `/plans` page for
-you; the provider and the stylesheet are the two it won't edit on your behalf.
-
-That gives you the whole round trip — `/signin`, `/callback`, an httpOnly session
-cookie, `/session`, `/entitlements`, `/plans`, `/addons`, `/apps`, `/sessions`,
-`/logout`. Config comes from the environment:
-
-| Variable | Required | Purpose |
-| --- | --- | --- |
-| `CONNECT_API_KEY` | yes | server-side credential |
-| `CONNECT_CLIENT_ID` | yes | OAuth client id |
-| `CONNECT_APP_URL` | no | non-production Connect instance |
-| `CONNECT_SESSION_COOKIE` | no | session cookie name |
-
-Register `{your origin}/api/connect/callback` as a redirect URI in the service's
-Integration tab — the one step this cannot do for you.
+## Next.js — reading the session
 
-No `next.config.ts` changes needed, including `transpilePackages`: `dist/` is
-already ES2022 with `"use client"` hoisted, so Turbopack and webpack both
-consume it as-is.
+The setup is [Quickstart](#quickstart-nextjs) above; this is the detail behind
+its step 6 — `getConnectSession()` / `requireConnectSession()` beyond the
+one-liner shown there.
 
-Reading the session server-side — no argument, no `headers()` dance:
+`requireConnectSession()` is `getConnectSession()` plus the check-and-redirect.
+Reach for the plain version when a missing session isn't an error — an
+optional account badge in a header, say:
 
 ```tsx
-// app/dashboard/page.tsx
 import { getConnectSession } from "@cosmoops/connect-sdk/next";
-import { redirect } from "next/navigation";
-
-export default async function DashboardPage() {
-  const session = await getConnectSession(); // UserResponse | null
-  if (!session) redirect("/api/connect/signin?next=/dashboard");
-  return <h1>{session.user.organizationName}</h1>;
-}
-```
 
-Or skip the check-and-redirect entirely — `requireConnectSession()` does both:
-
-```tsx
-import { requireConnectSession } from "@cosmoops/connect-sdk/next";
-
-export default async function DashboardPage() {
-  const session = await requireConnectSession(); // UserResponse — redirects if signed out
-  return <h1>{session.user.organizationName}</h1>;
-}
+const session = await getConnectSession(); // UserResponse | null
 ```
 
 Pass a `Request` — `getConnectSession(request)` — anywhere `next/headers` does
@@ -303,9 +404,6 @@ It reads `cookies()` transitively, so under `cacheComponents` it belongs inside
 a `<Suspense>` boundary like any other request-scoped read. A page that awaits
 it above every boundary gives up its static shell.
 
-You do **not** need `transpilePackages`. `dist/` is ES2022 with `"use client"`
-already hoisted, so Turbopack and webpack consume it as-is.
-
 ## Route protection and `proxy.ts`
 
 Nothing here is auto-wired, and nothing needs to be: this SDK ships no proxy and
@@ -340,11 +438,24 @@ export const config = { matcher: ["/dashboard/:path*", "/settings/:path*"] };
 
 **A cookie is not a session, and this check is not authorization.** The cookie
 holds an opaque Connect `sessionToken`; deciding whether it is still valid means
-asking Connect, and proxy runs on every matched request — so a real check here
-would put a network round trip in front of each one. Next's own guidance says
-the same thing: proxy is for [optimistic
-checks](https://nextjs.org/docs/app/guides/authentication#optimistic-checks-with-proxy-optional),
-"not ... a full session management or authorization solution."
+asking Connect, and proxy runs on every matched request — including
+[prefetched](https://nextjs.org/docs/app/getting-started/linking-and-navigating#prefetching)
+ones — so a real check here would put a network round trip in front of far
+more requests than the visitor actually makes.
+
+This isn't just this SDK's opinion — it's what Next.js's own [Authentication
+guide](https://nextjs.org/docs/app/guides/authentication#optimistic-checks-with-proxy-optional)
+recommends, word for word (verified against the docs bundled with the Next
+version in this repo's `node_modules`, since the hosted docs move faster than
+any one install):
+
+> Since Proxy runs on every route, including prefetched routes, it's important
+> to only read the session from the cookie (optimistic checks), and avoid
+> database checks to prevent performance issues.
+
+The snippet above is exactly that: a presence check, nothing more. Next is
+equally direct that this is as far as it goes — optimistic checks are "not
+\[...\] a full session management or authorization solution."
 
 An expired or revoked token still arrives as a cookie and still passes the
 snippet above. The authoritative check is `getConnectSession()` in the Server
@@ -405,19 +516,19 @@ that URL yourself instead.
 
 ```tsx
 import {
-  ConnectAppShell,
+  AppShell,
   ConnectLoginButton, ConnectRegisterButton,
-  ConnectUserMenu, ConnectAppsGrid, ConnectPlans,
+  ConnectUserButton, ConnectAppsGrid, ConnectPlans,
 } from "@cosmoops/connect-sdk/client";
 
-// The whole frame — sidebar, top bar, access gate. See "App shell" below.
-<ConnectAppShell name="Dispatch" nav={nav}>{children}</ConnectAppShell>
+// The whole frame — the rail, the access gate, Ask AI. See "App shell" below.
+<AppShell name="Dispatch" nav={nav} secondaryNav={settingsNav}>{children}</AppShell>
 
 // Or the pieces, if you already have a layout. The pair swaps automatically
 // on sign-in state.
-<ConnectAppsGrid />
+<ConnectAppsGrid variant="icon" />
 <ConnectLoginButton />
-<ConnectUserMenu />
+<ConnectUserButton variant="inline" />
 
 // Pricing page
 <ConnectPlans />
@@ -425,19 +536,25 @@ import {
 
 | Component | What it does |
 | --- | --- |
-| `ConnectAppShell` | **The whole application frame** — collapsible sidebar, top bar with the launcher and account menu, and your pages in the middle. Mounts `ConnectAccessGate` for you. |
-| `ConnectSideNav` | The sidebar's nav column on its own — sections, one level of children, active-route highlight — for an app that already has its own chrome. |
+| `AppShell` | **The whole application frame** — one collapsible rail carrying the brand, workspace switcher, both navs, the launcher and the account row, with your pages beside it. No top bar. Mounts `ConnectAccessGate` for you. The one `/client` export without the `Connect` prefix; alias it on import if your own layout shares the name. |
+| `ConnectSidebar` · `ConnectSidebarHeader` · `ConnectSidebarBody` · `ConnectSidebarFooter` · `ConnectSidebarRow` | The rail in pieces, for chrome the props cannot express. `AppShell` composes exactly these; they coordinate through `ConnectShellProvider`. |
+| `ConnectSidebarNav` | The rail's nav column on its own — sections, one level of children, active-route highlight — for an app that already has its own chrome. (Was `ConnectSideNav`.) |
 | `ConnectLoginButton` · `ConnectRegisterButton` | "Continue with Connect", in the shape people know from Google. Render nothing when signed in. |
-| `ConnectUserMenu` | Avatar, name, workspace. Profile, Manage subscription and Open Connect each open Connect in a new tab; Sign out acts in place. Renders nothing when signed out. |
+| `ConnectUserButton` | The account row at the foot of the rail — circular avatar, name over email — opening a modal with identity, sessions and the Connect destinations. Profile, Manage subscription and Open Connect each open Connect in a new tab; Sign out acts in place. Renders nothing when signed out. (Was `ConnectUserMenu`.) |
+| `ConnectProfileModal` | The same modal with no trigger, driven by `isOpen`/`onOpenChange` — for an app keeping its own account control. |
+| `ConnectWorkspaceSwitcher` | Sits in the rail's header. Hides itself for an account with one workspace; shows unusable ones disabled, with the reason. |
 | `ConnectAppsGrid` | Google-style launcher — grid icon opening a modal of every app this workspace can open. |
 | `ConnectPlans` | Monthly/annual toggle, features, add-ons, live discount, coupon field, and the subscribe / upgrade / downgrade / cancel flow. |
 | `ConnectPlansPage` | A whole `/plans` page — readiness banner, current subscription, and the grid. What `connect-sdk init` scaffolds. |
 | `ConnectSubscribeDialog` | The review step `ConnectPlans` opens — plan, GST, what happens to the current cycle. Exported so you can drive the flow from your own pricing page. |
+| `ConnectAskAi` | **Ask AI** — a chat panel grounded in the workspace's Context Index, streamed through your own bridge. Answers draw as well as write: tables, charts, metric tiles. Mounted by `AppShell` by default. |
+| `AiTable` · `AiChart` · `AiMetrics` · `AiTimeline` · `AiDetails` · `AiSteps` · `AiSources` | The seven widgets an Ask AI answer can draw, exported for rendering Connect's chat somewhere other than the panel. |
 | `ConnectAccessGate` | **The one gate to mount if you mount one.** Composes suspended / no-plan / onboarding-pending / payment-due into a single priority-ordered decision. Wrap your app content once. |
 | `ConnectSubscriptionGate` | Renders your module for a subscribed workspace, and `ConnectNoSubscriptionCard` for everyone else. Never flashes the upsell while loading. |
 | `ConnectNoSubscriptionCard` · `ConnectSubscriptionCard` | The same slot, unsubscribed and subscribed. Plan, status, renewal date, seats, and one way into Connect. |
-| `ConnectReadinessBanner` · `ConnectReadinessGate` | Every gate between this workspace and your service — KYC, payment method, seat headroom — each with the Connect screen that fixes it. |
+| `ConnectReadinessBanner` · `ConnectReadinessGate` | Every gate between this workspace and your application — KYC, payment method, seat headroom — each with the Connect screen that fixes it. |
 | `ConnectFeatureGate` | Renders a module only when `plan.features` includes its key. |
+| `ConnectWorkspaceTypeGate` | Renders a subtree only for an `"individual"` or `"business"` workspace — for dead controls, not access. |
 | `ConnectTrialBanner` | A running trial and the date it converts. Renders nothing otherwise. |
 | `ConnectAccountSessions` | Every device signed into this Connect account, with revoke. |
 | `ConnectUsageMeter` | Remaining balance of each consumable add-on, with overage and carry-forward. |
@@ -446,12 +563,12 @@ import {
 
 ### Hooks
 
-`useConnect` · `useConnectUser` · `useActivePath` · `useConnectAccessGate` · `useConnectEntitlements` · `useConnectPlans` · `useConnectApps` · `useConnectAddonUsage` · `useConnectSessions` · `useConnectResource` · `useConnectFeature` · `useConnectCheckout`
+`useConnect` · `useConnectUser` · `useConnectWorkspaceType` · `useConnectAudience` · `useActivePath` · `useConnectAccessGate` · `useConnectEntitlements` · `useConnectPlans` · `useConnectApps` · `useConnectAddonUsage` · `useConnectSessions` · `useConnectResource` · `useConnectFeature` · `useConnectCheckout`
 
 ### Metering
 
 ```tsx
-await client.billing.consumeAddon({ organizationId, addonId: "addon_sms", quantity: 1 });  // server
+await client.billing.consumeAddon({ workspaceId, addonId: "addon_sms", quantity: 1 });  // server
 <ConnectUsageMeter />                                                                     // browser
 ```
 
@@ -461,7 +578,7 @@ Invoices stay a deep link (`ConnectInvoicesButton`). A GST tax invoice is a lega
 
 ### Plan features: label vs key
 
-The catalogue read (`useConnectPlans`, `<ConnectPlans />`) reports `features` as `{ key, name, description }` — **render `name`, gate on `key`**. The subscription read (`useConnectEntitlements`, `hasFeature`, `<ConnectFeatureGate>`) reports `features` as a bare `string[]` of keys, and stays that way: that one is a contract your backend compares against, and a display label is neither stable nor comparable. `name` falls back to the key for a plan older than its service's feature catalog.
+The catalogue read (`useConnectPlans`, `<ConnectPlans />`) reports `features` as `{ key, name, description }` — **render `name`, gate on `key`**. The subscription read (`useConnectEntitlements`, `hasFeature`, `<ConnectFeatureGate>`) reports `features` as a bare `string[]` of keys, and stays that way: that one is a contract your backend compares against, and a display label is neither stable nor comparable. `name` falls back to the key for a plan older than its application's feature catalog.
 
 ### Gates
 
@@ -481,7 +598,7 @@ the order yourself:
 | State | What renders |
 | --- | --- |
 | `suspended` | A hard stop. Nothing the customer does clears it — only a Connect admin reactivating the workspace. |
-| `no_subscription` | "Choose a plan", linking to Connect's subscribe page for your service. |
+| `no_subscription` | "Choose a plan", linking to Connect's subscribe page for your application. |
 | `onboarding_pending` | Waiting on a reviewer. No action offered, because there is none. |
 | `blocked` | Any other blocking readiness code — verification, audience, seats — each with its own fix. |
 | `payment_retry` | **Your app still renders.** A dismissible banner counts down to the dunning deadline. |
@@ -519,7 +636,7 @@ The narrower gates still exist for gating *within* a cleared workspace:
 
 All of them render `loading` — never the fallback — while the answer is unknown, so a paying customer is never flashed an upsell for something they already have.
 
-**They are UX gates, not security boundaries.** Everything they read reaches your own origin and a browser can ignore it. The authoritative check is on your server: `client.entitlements.getReadiness(orgId)` and `client.entitlements.hasFeature(orgId, feature)`.
+**They are UX gates, not security boundaries.** Everything they read reaches your own origin and a browser can ignore it. The authoritative check is on your server: `client.entitlements.getReadiness(workspaceId)` and `client.entitlements.hasFeature(workspaceId, feature)`.
 
 ### Scaffolding
 
@@ -579,12 +696,12 @@ Cancelling uses the same machinery via `buildCancelUrl`. There is no *resume*: C
 "use client";
 import Link from "next/link";
 import { usePathname } from "next/navigation";
-import { ConnectAppShell } from "@cosmoops/connect-sdk/client";
+import { AppShell } from "@cosmoops/connect-sdk/client";
 import { LayoutDashboard, Receipt, Settings, Truck } from "lucide-react";
 
 export function Shell({ children }: { children: React.ReactNode }) {
   return (
-    <ConnectAppShell
+    <AppShell
       name="Dispatch"
       icon={<Truck />}
       activePath={usePathname()}
@@ -592,33 +709,38 @@ export function Shell({ children }: { children: React.ReactNode }) {
       nav={[
         { label: "Overview", href: "/", icon: <LayoutDashboard className="size-5" /> },
         { label: "Shipments", href: "/shipments", icon: <Truck className="size-5" /> },
+      ]}
+      // Pinned to the foot of the rail: the routes you go to in order to
+      // change how the job works, not to do it.
+      secondaryNav={[
         {
-          title: "Workspace",
+          label: "Settings",
+          href: "/settings",
+          icon: <Settings className="size-5" />,
           items: [
-            {
-              label: "Settings",
-              href: "/settings",
-              icon: <Settings className="size-5" />,
-              items: [
-                { label: "Members", href: "/settings/members" },
-                { label: "Billing", href: "/settings/billing" },
-              ],
-            },
-            { label: "Plans", href: "/plans", icon: <Receipt className="size-5" />, gateExempt: true },
+            { label: "Members", href: "/settings/members" },
+            { label: "Billing", href: "/settings/billing" },
           ],
         },
+        { label: "Plans", href: "/plans", icon: <Receipt className="size-5" />, gateExempt: true },
       ]}
     >
       {children}
-    </ConnectAppShell>
+    </AppShell>
   );
 }
 ```
 
-That is the entire layout of a service platform. Everything that should look
-identical across the family — the lockup, the rail geometry, the active-route
-treatment, the app launcher, the account menu, the mobile drawer — comes from
-here; only `name`, `icon` and `nav` differ per platform.
+That is the entire layout of an application platform. Everything that should
+look identical across the family — the lockup, the rail geometry, the
+active-route treatment, the app launcher, the account row, the mobile drawer —
+comes from here; only `name`, `icon` and the two navs differ per platform.
+
+**There is no top bar.** The launcher and the account row live at the foot of
+the rail, one press from wherever the pointer already is, and a page's own
+heading belongs to the page — put it in `ConnectPageShell` from
+`@cosmoops/connect-sdk/ui`. Below `md` a slim bar carries the drawer trigger
+and nothing else.
 
 **Routing is a prop.** The SDK ships into any React app and cannot import
 `next/link`, so `renderLink` is how your router gets involved; the default is a
@@ -627,13 +749,13 @@ plain `<a>`, which works everywhere and costs a full page load. Pass
 `window.location` and patches `history.pushState` to hear about client-side
 navigations, which is guesswork your router never has to do.
 
-**The access gate is on by default.** `ConnectAppShell` is exactly the "wrap
+**The access gate is on by default.** `AppShell` is exactly the "wrap
 your app content once" place `ConnectAccessGate` asks for, so it mounts one
 around `children` — an app that ships a shell and forgets the gate is an app
 that lets a suspended workspace keep working. The chrome is never gated: the
 sidebar, the lockup, the account menu and sign-out stay reachable in every
 blocked state. Routes that resolve a block rather than needing one — your
-pricing page — are flagged where they are declared:
+pricing page — are flagged where they are declared, in either nav:
 
 ```tsx
 { label: "Plans", href: "/plans", gateExempt: true }
@@ -644,28 +766,51 @@ page that sells them one, and is told to choose a plan. Pass `gate={false}` to
 opt out entirely, or `gateExemptRoutes` for a path that is not in the sidebar
 at all.
 
+**Ask AI is on by default too**, for the same reason: a family of application
+platforms should answer questions the same way, and a feature every partner has
+to remember to switch on is a feature most of them do not have. It stays inert
+until it can work — nothing renders for a signed-out visitor, and a workspace
+whose Context Index is off gets a message in the panel rather than a broken
+answer. Pass `askAi={false}` to leave it out, or an object to override its
+heading, copy or markdown plugins.
+
+It needs two things you control: the workspace's Context Index turned on in
+Connect, and `ai:chat` on the API key behind your bridge.
+
 Other things worth knowing:
 
-- **The rail collapses to icons** and remembers the choice per browser
-  (`localStorage`). Drive it yourself with `collapsed` + `onCollapsedChange`,
-  or pin it open with `collapsible={false}`.
-- **Below `md` there is no rail**, only a drawer behind the top bar's menu
+- **The rail starts collapsed** and remembers the choice per browser
+  (`localStorage`). The icon rail is the resting state; expanding is the
+  deliberate act. Expanded, the collapse control sits at the header's trailing
+  edge; collapsed, hovering the lockup swaps it for the expand glyph — so the
+  rail spends no row on a permanent control, at the cost of the lockup no
+  longer being a link home while collapsed. Pass `defaultCollapsed={false}` to
+  open by default, drive it with `collapsed` + `onCollapsedChange`, or pin it
+  open with `collapsible={false}`.
+- **The collapse animates width and nothing else.** Every row is laid out so
+  its glyph sits on the same horizontal centre in both states, and labels are
+  clipped rather than re-measured — so no row reflows and nothing drifts
+  sideways mid-transition.
+- **Below `md` there is no rail**, only a drawer behind the mobile bar's menu
   button — a 64px icon strip on a phone is a worse drawer, not a smaller one.
 - **Children unfold only on the branch you are on.** A sidebar that opens
   every branch at once is a sitemap.
 - **No `isSignedIn` branch, in here or in yours.** The auth buttons render
-  nothing once a session exists, the account menu renders nothing without one,
+  nothing once a session exists, the account row renders nothing without one,
   and the launcher renders nothing when signed out.
-- `title`, `headerActions`, `sidebarFooter` and `footer` are slots;
-  `contentClassName` replaces the content pane's default max-width and
-  padding.
-- `theme` / `onThemeChange` pass straight through to `ConnectUserMenu` — the
+- `secondaryNav`, `sidebarFooter` and `footer` are slots; `contentClassName`
+  replaces the content pane's default max-width and padding. (`title` and
+  `headerActions` are gone with the top bar — see the 0.12.0 changelog entry.)
+- `theme` / `onThemeChange` pass straight through to `ConnectUserButton` — the
   SDK has no theme provider of its own, deliberately.
 
-`ConnectSideNav` is the nav column alone, for an app with chrome it already
-likes. `resolveActivePath` and `isNavItemActive` are the same pure functions
-the rail highlights with, exported so a breadcrumb or a document title derived
-from your nav cannot disagree with it.
+`ConnectSidebarNav` is the nav column alone, for an app with chrome it already
+likes, and `ConnectSidebar` / `ConnectSidebarHeader` / `ConnectSidebarBody` /
+`ConnectSidebarFooter` / `ConnectSidebarRow` are the rest of the rail — the
+exact pieces `AppShell` composes, so chrome the props cannot express is a
+rearrangement rather than a fork. `resolveActivePath` and `isNavItemActive` are
+the same pure functions the rail highlights with, exported so a breadcrumb or a
+document title derived from your nav cannot disagree with it.
 
 ### Logo
 
@@ -686,7 +831,7 @@ Each platform passes only what differs — `name` and `icon`. Mark geometry, wor
 @import "@cosmoops/connect-sdk/theme.css";
 ```
 
-One shared **HeroUI v3** theme for every service platform. The components paint with semantic tokens only — `accent`, `muted`, `surface`, `separator`, `danger` — never a hardcoded colour, so one edit to the theme restyles all of them everywhere at once. To diverge on brand, redefine individual tokens *after* the import rather than forking the file.
+One shared **HeroUI v3** theme for every application platform. The components paint with semantic tokens only — `accent`, `muted`, `surface`, `separator`, `danger` — never a hardcoded colour, so one edit to the theme restyles all of them everywhere at once. To diverge on brand, redefine individual tokens *after* the import rather than forking the file.
 
 Requires `@heroui/react`, `lucide-react` and `motion` as peers (optional — server-only consumers need none of them). `motion` drives the components' entrance and state transitions, and respects `prefers-reduced-motion`.
 
@@ -696,6 +841,113 @@ The *flow* is in your app; the *payment* is not. A plan change is not one write
 
 So the hand-off is a URL, and Connect renders it as a modal over the relevant page (an intercepted parallel route) — the customer lands on the confirmation for the plan they picked, and returns to a subscription that is already correct.
 
+## Release notes
+
+Full history: [CHANGELOG.md](./CHANGELOG.md). Latest first:
+
+### 0.12.0 — breaking
+
+The application shell is one column. **The top bar is gone**; the rail holds
+everything it used to, and starts collapsed.
+
+- **`title` and `headerActions` are removed** with the bar that held them. A
+  page's heading goes in `ConnectPageShell` (from `/ui`), next to that page's
+  own breadcrumbs and actions; an application-level control goes in
+  `sidebarFooter` as a `ConnectSidebarRow`.
+- **`defaultCollapsed` now defaults to `true`.** Pass `false` for 0.11's
+  behaviour.
+- **`ConnectSideNav` → `ConnectSidebarNav`**, **`ConnectUserMenu` →
+  `ConnectUserButton`**. Both old names remain as deprecated aliases.
+  `AppShell` keeps its name — the one export here without the `Connect`
+  prefix, as decided in 0.8.0.
+- **New:** `secondaryNav` (a second nav group pinned to the foot of the rail),
+  `ConnectProfileModal` (the account modal with no trigger), and the rail's
+  own pieces — `ConnectSidebar`, `ConnectSidebarHeader`, `ConnectSidebarBody`,
+  `ConnectSidebarFooter`, `ConnectSidebarRow`, `ConnectShellProvider`,
+  `useConnectShell`, `sidebarRowClass`.
+- **The workspace switcher moved into the rail's header** and is collapse-aware;
+  the account row sits at the foot with a circular avatar.
+- **Fixed:** the closed Ask AI panel occupied 400px at `lg` and up on every page
+  with `askAi` on; sidebar contrast (the active row was **below WCAG AA** in
+  both schemes); the launcher and account rows looked permanently selected.
+
+### 0.11.0 — breaking
+
+- **`ConnectUser.workspaceId`, `workspaceName` and `workspaceType` are
+  nullable.** They are `null` for exactly one thing: a **Connect platform
+  staff** session, which belongs to no workspace. If you never enable staff
+  access — it is off by default — this is a type narrow and nothing else.
+  `?? ""` is the wrong fix: decide what your tenanting does with a session that
+  has no tenant.
+- **Connect platform staff sign-in**, `platformAccess` on `exchangeCode()` and
+  `getUser()`, `<ConnectPlatformGate>` and `useConnectPlatformAccess()`.
+
+### 0.10.0
+
+- **`@cosmoops/connect-sdk/ui`** — `ConnectPageShell`, `ConnectSection`,
+  `ConnectEmptyState`, `ConnectStatusChip`, `ConnectSettingRow`. Deliberately
+  *not* a `"use client"` module, so a page shell does not become a client
+  boundary.
+- `ConnectLinkButton`, `ConnectConfirmDialog`, `ConnectCursorPagination`,
+  `ConnectFilterTabs`, `ConnectAccountSessions` — built since 0.8 and reachable
+  from no entry point until now.
+- `ConnectWorkspaceSwitcher`, `useConnectWorkspaces()`,
+  `useConnectWorkspaceMembers()`, and the `workspaces` resource on the server
+  client.
+
+### 0.9.0
+
+- **Ask AI**, mounted by `AppShell` by default — a chat panel grounded in the
+  workspace's Context Index, streamed through a new `POST /ai/chat` route on
+  your own bridge. The workspace comes from the caller's session, never the
+  browser.
+- **Answers draw as well as write.** Connect's model calls presentation tools
+  and the panel renders them natively: a sortable table with CSV export, a
+  chart, metric tiles, timelines, fact sheets, procedures, citations. Values
+  arrive raw with a format tag, so they are formatted in the viewer's locale
+  and a column still sorts numerically. The seven widgets are exported.
+- **`streamdown` is a new optional peer dependency** — see step 1 and step 4 of
+  the quickstart. Two lines of host setup; skip both with `askAi={false}`.
+- **`user.workspaceType`, `audience`**, `<ConnectWorkspaceTypeGate>`,
+  `useConnectWorkspaceType()`, `useConnectAudience()`.
+- **`streamResource()`** on `useConnect()` — POST through the bridge and get
+  the raw streaming `Response` back.
+- **Fixed:** `ai.chat()` no longer has its stream cut off mid-answer by the
+  transport's 20s timeout.
+
+*0.8.0 was never published; its one breaking change is in this release.*
+
+### 0.8.0 — breaking (folded into 0.9.0)
+
+- **`ConnectAppShell` renamed to `AppShell`.** Same props, same behaviour —
+  only the name changed. Every other `/client` export keeps its `Connect`
+  prefix; this is the one deliberate exception.
+
+  ```diff
+  - import { ConnectAppShell, type ConnectAppShellProps } from "@cosmoops/connect-sdk/client";
+  + import { AppShell, type AppShellProps } from "@cosmoops/connect-sdk/client";
+  ```
+
+  If your own layout component is also named `AppShell`, alias the import:
+  `import { AppShell as ConnectAppShell } from "..."`.
+
+### 0.6.0
+
+- **`AppShell`** (then `ConnectAppShell`) — the application frame every
+  platform was otherwise writing by hand: collapsible sidebar, top bar with
+  the app launcher and account menu, mobile drawer, `ConnectAccessGate`
+  mounted around your content by default.
+- **`ConnectSideNav`** — the sidebar's nav column alone, for an app with
+  chrome it already likes.
+- The nav model as data — `ConnectNav` / `ConnectNavItem` / `ConnectNavSection`
+  — plus the pure functions the rail resolves the active route with.
+
+See [CHANGELOG.md](./CHANGELOG.md) for 0.5.0 and earlier.
+
+Upgrading past a minor version? Read that version's entry first — per the 0.x
+convention at the top of this file, a minor bump here is allowed to break
+something, and the changelog says what and how to migrate.
+
 ## Development
 
 ```bash