@cosmoops/connect-sdk 0.7.0 → 0.9.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 Integration tab
+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 Integration tab, 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 sidebar, top bar and 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 Integration tab 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
+## Next.js — reading the session
 
-Two files, no arguments.
+The setup is [Quickstart](#quickstart-nextjs) above; this is the detail behind
+its step 6 — `getConnectSession()` / `requireConnectSession()` beyond the
+one-liner shown there.
 
-```ts
-// app/api/connect/[...connect]/route.ts
-export { GET, POST } from "@cosmoops/connect-sdk/next";
-```
+`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/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.
-
-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.
-
-Reading the session server-side — no argument, no `headers()` dance:
-
-```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,13 +516,13 @@ that URL yourself instead.
 
 ```tsx
 import {
-  ConnectAppShell,
+  AppShell,
   ConnectLoginButton, ConnectRegisterButton,
   ConnectUserMenu, 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 — sidebar, top bar, access gate, Ask AI. See "App shell" below.
+<AppShell name="Dispatch" nav={nav}>{children}</AppShell>
 
 // Or the pieces, if you already have a layout. The pair swaps automatically
 // on sign-in state.
@@ -425,7 +536,7 @@ 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. |
+| `AppShell` | **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. |
 | `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. |
@@ -433,11 +544,14 @@ import {
 | `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 +560,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 +575,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 +595,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 +633,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 +693,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()}
@@ -610,12 +724,12 @@ export function Shell({ children }: { children: React.ReactNode }) {
       ]}
     >
       {children}
-    </ConnectAppShell>
+    </AppShell>
   );
 }
 ```
 
-That is the entire layout of a service platform. Everything that should look
+That is the entire layout of a application 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.
@@ -627,7 +741,7 @@ 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
@@ -644,6 +758,17 @@ 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
@@ -686,7 +811,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 +821,63 @@ 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.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

package/dist/cjs/client/components/access-gate.js

@@ -25,9 +25,17 @@ function formatDate(iso) {
  * `ConnectReadinessGate`/`ConnectReadinessBanner` already use. `ConnectAccessGate`
  * is a priority ordering over the same data, not a second opinion about it.
  *
- * Priority, first match wins: `suspended` > `no_subscription` >
- * `onboarding_pending` > any other blocking code (`blocked`) >
- * `payment_retry` (advisory - `children` still render) > `clear`.
+ * Priority, first match wins: `suspended` > `audience_mismatch` >
+ * `no_subscription` > `onboarding_pending` > any other blocking code
+ * (`blocked`) > `payment_retry` (advisory - `children` still render) >
+ * `clear`.
+ *
+ * `audience_mismatch` outranks `no_subscription` deliberately, and the
+ * ordering is the whole point of it: a workspace of the wrong account type
+ * carries BOTH blockers at once, and showing the subscription one first sent
+ * the customer to a plan picker whose subscribe call
+ * (`ActivateSubscriptionUseCase`) rejects them for the audience anyway. The
+ * account type is the reason; the missing subscription is a consequence.
  */
 function useConnectAccessGate() {
     const { session, isLoading: sessionLoading } = (0, provider_js_1.useConnect)();
@@ -50,6 +58,10 @@ function useConnectAccessGate() {
     const suspended = blocking.find((b) => b.code === "workspace_suspended");
     if (suspended)
         return { state: "suspended", blocker: suspended, paymentRetry: null };
+    const audienceMismatch = blocking.find((b) => b.code === "audience_mismatch");
+    if (audienceMismatch) {
+        return { state: "audience_mismatch", blocker: audienceMismatch, paymentRetry: null };
+    }
     const noSubscription = blocking.find((b) => b.code === "subscription_missing");
     if (noSubscription)
         return { state: "no_subscription", blocker: noSubscription, paymentRetry: null };
@@ -109,6 +121,29 @@ function ConnectAccessGate({ children, fallback, loading, className }) {
     return ((0, jsx_runtime_1.jsx)(jsx_runtime_1.Fragment, { children: fallback ?? (0, jsx_runtime_1.jsx)(AccessGateFallback, { state: gate.state, blocker: gate.blocker, className: className }) }));
 }
 function AccessGateFallback({ state, blocker, className, }) {
+    if (state === "audience_mismatch") {
+        // `requiredWorkspaceType` rather than the message, which is documented as
+        // human-facing and subject to rewording - the title has to name the right
+        // account type even after someone rephrases the sentence below it.
+        const required = blocker?.requiredWorkspaceType ?? null;
+        return ((0, jsx_runtime_1.jsx)(GateCard, { icon: required === "individual" ? lucide_react_1.User : lucide_react_1.Building2, iconClassName: "text-muted", title: required === "business"
+                ? "Business account required"
+                : required === "individual"
+                    ? "Individual account required"
+                    : "Not available for this account type", 
+            // The server names the application in its own message, which reads
+            // better than anything composable here; the fallback covers a blocker
+            // that arrived without one.
+            message: blocker?.message ??
+                (required
+                    ? `This application is only available to ${required} accounts.`
+                    : "This application isn't available to this account's type."), 
+            // Deliberately no action, even if one were sent: `Workspace.type` is
+            // set at sign-up and no screen changes it, so any button here would
+            // only move the dead end somewhere else. Switching means a different
+            // account, which is a conversation with support, not a link.
+            resolveUrl: null, className: className }));
+    }
     if (state === "no_subscription") {
         return ((0, jsx_runtime_1.jsx)(GateCard, { icon: lucide_react_1.CreditCard, iconClassName: "text-accent", title: "Choose a plan to continue", message: blocker?.message ?? "This workspace isn't subscribed to this application yet.", actionLabel: "See plans", resolveUrl: blocker?.resolveUrl ?? null, className: className }));
     }
@@ -118,7 +153,7 @@ function AccessGateFallback({ state, blocker, className, }) {
     if (state === "onboarding_pending") {
         return ((0, jsx_runtime_1.jsx)(GateCard, { icon: lucide_react_1.Clock, iconClassName: "text-muted", title: "Waiting on approval", message: blocker?.message ?? "This workspace is waiting on approval before it can use this application.", resolveUrl: null, className: className }));
     }
-    // "blocked" - any other blocking code (verification, audience, seats, ...).
+    // "blocked" - any other blocking code (verification, seats, ...).
     // Full fidelity for a code this component doesn't special-case: the same
     // banner-in-a-card `ConnectReadinessGate` falls back to, rather than
     // `GateCard`'s single-blocker shape - there can be more than one of these