docs(demo): host the his-demo as a static SPA at /fhir-dsl/demo

Bring the Caduceus HIS demo onto the docs site. Patient list/detail,
FHIRPath playground, and the SMART OAuth flow all work statically; the
chatbot drawer is hidden in this mode because /api/chat + /api/mcp need
a server runtime.

Build pipeline:

- apps/his-demo/vite.config.ts gains a DEMO_STATIC=1 + DEMO_BASE_PATH
  env-var-driven branch that swaps the Nitro plugins for SPA mode and
  prerendering. Normal pnpm dev / pnpm demo:gen flows are unchanged.
- apps/his-demo/src/router.tsx reads import.meta.env.BASE_URL and passes
  it as TanStack Router's basepath so client-side navigation stays
  correct under /fhir-dsl/demo/.
- apps/his-demo/src/routes/__root.tsx hides the chat trigger + drawer
  whenever BASE_URL !== '/' (i.e. in any subpath / static deploy).
- .github/workflows/deploy-docs.yml: after Docusaurus builds, gen R4
  types, build the demo with DEMO_STATIC=1, copy dist/client into
  apps/docs/build/demo/, and dual-publish _shell.html as both index.html
  (root) and 404.html (so deep routes fall through to the SPA shell).
- apps/docs adds a /docs/demo page describing what the demo shows + how
  to run the full chatbot version locally, plus a "Demo" navbar entry
  using pathname:///demo/ to bypass Docusaurus's broken-link checker
  (the demo lives outside the docs tree).

Author: awbx

.github/workflows/deploy-docs.yml

@@ -5,6 +5,8 @@ on:
     branches: [main]
     paths:
       - 'apps/docs/**'
+      - 'apps/his-demo/**'
+      - 'packages/**'
       - '.github/workflows/deploy-docs.yml'
   workflow_dispatch:
 
@@ -40,6 +42,31 @@ jobs:
         working-directory: apps/docs
         run: pnpm build
 
+      - name: Generate FHIR types for demo
+        working-directory: apps/his-demo
+        run: pnpm gen
+
+      - name: Build demo (static SPA)
+        working-directory: apps/his-demo
+        env:
+          DEMO_STATIC: '1'
+          DEMO_BASE_PATH: /fhir-dsl/demo/
+        run: pnpm build
+
+      - name: Stage demo into docs build
+        run: |
+          set -euo pipefail
+          DEMO_SRC=apps/his-demo/dist/client
+          DEMO_DST=apps/docs/build/demo
+          mkdir -p "$DEMO_DST"
+          cp -R "$DEMO_SRC"/. "$DEMO_DST"/
+          # GitHub Pages serves /demo/ → /demo/index.html (root-route SPA shell);
+          # /demo/<deep-route> → /demo/404.html (which is the same SPA shell, so the
+          # client-side router handles the deep route after hydration).
+          cp "$DEMO_DST/_shell.html" "$DEMO_DST/index.html"
+          cp "$DEMO_DST/_shell.html" "$DEMO_DST/404.html"
+          echo "demo size: $(du -sh $DEMO_DST | cut -f1)"
+
       - name: Upload artifact
         uses: actions/upload-pages-artifact@v3
         with:

apps/docs/docs/demo.md

@@ -0,0 +1,58 @@
+---
+id: demo
+title: Live Demo — Caduceus HIS
+description: A working hospital information system built with fhir-dsl — typed search, FHIRPath playground, SMART-on-FHIR patient launch, and a Claude chatbot wired through MCP.
+sidebar_label: Live Demo
+sidebar_position: 100
+---
+
+# Live Demo — Caduceus HIS
+
+**Caduceus** is a hospital information system demo that uses **every published `@fhir-dsl/*` package** end-to-end. It's the surface-freeze smoke test for v1.x — and the most concrete way to see what the toolchain looks like in a real React app.
+
+**→ [Live demo](pathname:///demo/)**  ·  **[Source on GitHub](https://github.com/awbx/fhir-dsl/tree/main/apps/his-demo)**
+
+## What's in the demo
+
+| Pillar | What it shows | Packages exercised |
+|---|---|---|
+| **Patient list / detail** | Typed search with `where` / `include` / `sort`, profile-narrowing toggle (US Core), FHIRPath-driven write-back via JSON Patch, optimistic update + rollback on `FhirRequestError` | `@fhir-dsl/core`, `@fhir-dsl/runtime`, `@fhir-dsl/fhirpath`, `@fhir-dsl/tanstack-query` |
+| **SMART-on-FHIR launch** | Full v2 flow through the SMART Health IT sandbox: discovery → PKCE → code exchange → token persistence | `@fhir-dsl/smart` |
+| **FHIRPath playground** | Live compile + evaluate against sample resources, UCUM-aware Quantity demo, terminology hooks demo | `@fhir-dsl/fhirpath` |
+| **Claude chatbot (full version only)** | LLM tool-use loop wired to an in-process MCP server, with audit timeline | `@fhir-dsl/mcp`, `@anthropic-ai/sdk` |
+
+## Two deployment flavors
+
+The demo is a TanStack Start app with both client and server routes. We ship two builds:
+
+- **GitHub Pages (this site, `/demo/`)** — a **static SPA build**. Patient list/detail, FHIRPath playground, and the SMART login flow all work because they're client-only. **The chatbot is disabled** because it requires server-side calls to the Anthropic SDK and the in-process MCP dispatcher.
+- **Full self-host** — build from the source repo and run with `pnpm demo` for the complete experience including the chatbot. Requires `ANTHROPIC_API_KEY` in your environment.
+
+## Run the full version locally
+
+```bash
+git clone https://github.com/awbx/fhir-dsl.git
+cd fhir-dsl
+pnpm install
+pnpm demo:gen     # generates R4 FHIR types into apps/his-demo/src/fhir/r4
+pnpm demo         # runs the dev server with chatbot + MCP enabled
+```
+
+Open `http://localhost:3000` and click **"Login with SMART"** to start the patient-launch dance. Drop your `ANTHROPIC_API_KEY` in `apps/his-demo/.env.local` first if you want the chatbot.
+
+## Architecture
+
+The demo is structured as a **TanStack Start app** with file-based routing and shadcn/ui. The interesting bits to read:
+
+- [`src/routes/patients.$id.tsx`](https://github.com/awbx/fhir-dsl/blob/main/apps/his-demo/src/routes/patients.%24id.tsx) — typed search, US Core profile narrowing toggle, FHIRPath write-back via JSON Patch
+- [`src/routes/playground.tsx`](https://github.com/awbx/fhir-dsl/blob/main/apps/his-demo/src/routes/playground.tsx) — Monaco editor wired to live FHIRPath compile/evaluate
+- [`src/server/mcp-singleton.ts`](https://github.com/awbx/fhir-dsl/blob/main/apps/his-demo/src/server/mcp-singleton.ts) — `@fhir-dsl/mcp` dispatcher mounted in-process on the TanStack Start server
+- [`src/server/claude.ts`](https://github.com/awbx/fhir-dsl/blob/main/apps/his-demo/src/server/claude.ts) — Anthropic SDK tool-use loop bound to the MCP dispatcher (max 8 tool-call steps per turn)
+- [`src/lib/use-fhir-client.ts`](https://github.com/awbx/fhir-dsl/blob/main/apps/his-demo/src/lib/use-fhir-client.ts) — `createClient` wired to a `SmartClient` `AuthProvider`
+
+## Related
+
+- [Architecture overview](./architecture/overview.md) — how the eleven packages compose
+- [SMART on FHIR guide](./guides/smart.md) — the auth flow the demo exercises
+- [MCP guide](./guides/mcp.md) — the chatbot's tool surface
+- [`@fhir-dsl/tanstack-query`](./api/tanstack-query.md) — the React Query bindings every page in the demo uses

apps/docs/docusaurus.config.js

@@ -173,6 +173,15 @@ const config = {
             position: 'left',
             label: 'Docs',
           },
+          {
+            // pathname:// prefix bypasses Docusaurus's broken-link checker —
+            // the demo lives outside the Docusaurus tree (built separately and
+            // copied into build/demo/ by the deploy workflow).
+            href: 'pathname:///demo/',
+            label: 'Demo',
+            position: 'left',
+            target: '_self',
+          },
           {
             href: 'https://github.com/awbx/fhir-dsl',
             label: 'GitHub',

apps/docs/sidebars.js

@@ -84,6 +84,7 @@ const sidebars = {
         'recipes/conditional-transaction',
       ],
     },
+    'demo',
     'edge-cases',
     'llm-usage',
     {

apps/his-demo/src/router.tsx

@@ -7,9 +7,15 @@ import { getContext } from './integrations/tanstack-query/root-provider'
 export function getRouter() {
   const context = getContext()
 
+  // Strip trailing slash so basepath '/fhir-dsl/demo/' becomes '/fhir-dsl/demo'.
+  // TanStack Router expects no trailing slash; '/' stays as '/' for normal builds.
+  const rawBase = (import.meta.env.BASE_URL ?? '/').replace(/\/$/, '')
+  const basepath = rawBase === '' ? '/' : rawBase
+
   const router = createTanStackRouter({
     routeTree,
     context,
+    basepath,
     scrollRestoration: true,
     defaultPreload: 'intent',
     defaultPreloadStaleTime: 0,

apps/his-demo/src/routes/__root.tsx

@@ -20,6 +20,11 @@ interface MyRouterContext {
 	queryClient: QueryClient;
 }
 
+// In static SPA builds (GitHub Pages at /fhir-dsl/demo) the /api/chat and
+// /api/mcp server routes don't exist. Hide the chatbot UI to keep the demo
+// honest about what's actually working.
+const IS_STATIC = import.meta.env.BASE_URL !== "/";
+
 export const Route = createRootRouteWithContext<MyRouterContext>()({
 	head: () => ({
 		meta: [
@@ -40,7 +45,7 @@ function RootDocument({ children }: { children: React.ReactNode }) {
 			</head>
 			<body className="min-h-dvh bg-background text-foreground antialiased">
 				<AppShell>{children}</AppShell>
-				<ChatDrawer />
+				{IS_STATIC ? null : <ChatDrawer />}
 				<TanStackDevtools
 					config={{ position: "bottom-right" }}
 					plugins={[
@@ -81,13 +86,15 @@ function AppShell({ children }: { children: React.ReactNode }) {
 						>
 							Playground
 						</Link>
-						<button
-							type="button"
-							className="flex items-center gap-1 rounded border border-border px-2 py-1 text-xs text-muted-foreground hover:bg-muted"
-							data-chatbot-trigger
-						>
-							<MessageSquare className="h-3.5 w-3.5" /> Chat
-						</button>
+						{IS_STATIC ? null : (
+							<button
+								type="button"
+								className="flex items-center gap-1 rounded border border-border px-2 py-1 text-xs text-muted-foreground hover:bg-muted"
+								data-chatbot-trigger
+							>
+								<MessageSquare className="h-3.5 w-3.5" /> Chat
+							</button>
+						)}
 					</nav>
 				</div>
 			</header>

apps/his-demo/vite.config.ts

@@ -7,15 +7,33 @@ import viteReact from '@vitejs/plugin-react'
 import tailwindcss from '@tailwindcss/vite'
 import { nitro } from 'nitro/vite'
 
+// Set DEMO_STATIC=1 to build a static SPA (no server routes) for hosting on
+// GitHub Pages at https://awbx.github.io/fhir-dsl/demo. The chatbot drawer is
+// disabled in this mode because /api/chat + /api/mcp need a server runtime.
+const STATIC_BUILD = process.env.DEMO_STATIC === '1'
+const BASE_PATH = process.env.DEMO_BASE_PATH ?? '/'
+
 const config = defineConfig({
+  base: BASE_PATH,
   resolve: { tsconfigPaths: true },
-  plugins: [
-    devtools(),
-    nitro({ rollupConfig: { external: [/^@sentry\//] } }),
-    tailwindcss(),
-    tanstackStart(),
-    viteReact(),
-  ],
+  plugins: STATIC_BUILD
+    ? [
+        tailwindcss(),
+        tanstackStart({
+          spa: {
+            enabled: true,
+            prerender: { enabled: true },
+          },
+        }),
+        viteReact(),
+      ]
+    : [
+        devtools(),
+        nitro({ rollupConfig: { external: [/^@sentry\//] } }),
+        tailwindcss(),
+        tanstackStart(),
+        viteReact(),
+      ],
 })
 
 export default config