chore: import upstream snapshot with attribution

showcase/integrations/langroid/qa/agent-config.md

@@ -0,0 +1,43 @@
+# QA: Agent Config Object — Langroid
+
+## Prerequisites
+
+- Demo is deployed and accessible
+- Agent backend reachable at `/api/copilotkit-agent-config`
+- Langroid agent server running (see `/api/health`)
+
+## Test Steps
+
+### 1. Config UI
+
+- [ ] Navigate to `/demos/agent-config`
+- [ ] Verify `data-testid="agent-config-card"` is visible
+- [ ] Verify Tone / Expertise / Response length selects are rendered
+
+### 2. Forwarded properties reach the agent
+
+- [ ] Change Tone to "enthusiastic"
+- [ ] Send "Hello" and verify a response is produced; tone should read as noticeably upbeat/warm
+- [ ] Change Expertise to "expert" and Response length to "detailed"
+- [ ] Send "Explain how LLM tool calling works" — verify the response uses domain terminology freely and is multiple sentences (not 1 to 2)
+- [ ] Change Response length to "concise" and Expertise to "beginner"
+- [ ] Send the same question — response should be 1 to 2 sentences, avoid jargon, and define any technical term the first time it appears
+
+### 3. Network inspection (optional, deeper verification)
+
+- [ ] Open DevTools Network panel
+- [ ] Send a message and inspect the POST to `/api/copilotkit-agent-config`
+- [ ] In the request body, verify `forwardedProps.config.configurable.properties`
+      contains `tone`, `expertise`, and `responseLength` with the selected values
+- [ ] The flat keys `forwardedProps.tone` / `.expertise` / `.responseLength`
+      should NOT be present — the route repacks them under `config.configurable.properties`
+
+## Expected Results
+
+- Selecting different config values visibly changes the assistant's voice,
+  depth of explanation, and response length.
+- The `/api/copilotkit-agent-config` request body shows the repacked shape
+  (flat provider keys land under `forwardedProps.config.configurable.properties`).
+- The Langroid backend receives the properties (via AG-UI `forwarded_props`)
+  and appends style directives to its system prompt for that run only; other
+  demos remain unaffected.

showcase/integrations/langroid/qa/agentic-chat-reasoning.md

@@ -0,0 +1,11 @@
+# QA: Agentic Chat (Reasoning) — Langroid
+
+NOTE: The Langroid AG-UI adapter does not currently emit
+`REASONING_MESSAGE_*` events. The custom `reasoningMessage` slot is wired,
+but the reasoning card only renders once the backend emits such messages.
+
+## Test Steps
+
+- [ ] Navigate to /demos/agentic-chat-reasoning
+- [ ] Verify chat input is visible
+- [ ] Send a query; verify a normal assistant reply

showcase/integrations/langroid/qa/agentic-chat.md

@@ -0,0 +1,62 @@
+# QA: Agentic Chat — Langroid
+
+## Prerequisites
+
+- Demo is deployed and accessible
+- Agent backend is healthy (check /api/health)
+
+## Test Steps
+
+### 1. Basic Functionality
+
+- [ ] Navigate to the agentic-chat demo page
+- [ ] Verify the chat interface loads with a text input placeholder "Type a message"
+- [ ] Verify the background container (`data-testid="background-container"`) is visible
+- [ ] Verify the default background color is the theme default (rgb(250, 250, 249))
+- [ ] Send a basic message (e.g. "Hello")
+- [ ] Verify the agent responds with a text message
+
+### 2. Feature-Specific Checks
+
+#### Suggestions
+
+- [ ] Verify "Change background" suggestion button is visible
+- [ ] Verify "Generate sonnet" suggestion button is visible
+- [ ] Click the "Change background" suggestion
+- [ ] Verify the suggestion either populates the input or sends the message
+
+#### Background Change (useFrontendTool)
+
+- [ ] Ask "Change the background to a sunset gradient"
+- [ ] Verify the background container style changes from the default
+- [ ] Verify the change_background tool returns a success status
+
+#### Weather Render Tool (useRenderTool)
+
+- [ ] Type "What's the weather in Tokyo?"
+- [ ] Verify loading state shows "Loading weather..." (`data-testid="weather-info-loading"`)
+- [ ] Verify WeatherCard renders (`data-testid="weather-info"`) with:
+  - [ ] City name displayed
+  - [ ] Temperature in degrees C
+  - [ ] Humidity percentage
+  - [ ] Wind speed in mph
+  - [ ] Conditions text
+
+#### Agent Context
+
+- [ ] Verify the agent knows the user's name is "Bob" (provided via useAgentContext)
+- [ ] Ask "What is my name?" and verify the agent responds with "Bob"
+
+### 3. Error Handling
+
+- [ ] Send an empty message (should be handled gracefully)
+- [ ] Verify no console errors during normal usage
+- [ ] Send a very long message and verify no UI breakage
+
+## Expected Results
+
+- Chat loads within 3 seconds
+- Agent responds within 10 seconds
+- Background changes are instant after tool execution
+- Weather card renders with all data fields populated
+- No UI errors or broken layouts

showcase/integrations/langroid/qa/auth.md

@@ -0,0 +1,68 @@
+# QA: Authentication — Langroid
+
+## Prerequisites
+
+- Demo deployed and accessible at /demos/auth
+- Langroid agent backend healthy (check /api/health)
+- The route `/api/copilotkit-auth` rejects requests missing the Bearer header
+
+## Test Steps
+
+### 1. Initial authenticated state
+
+- [ ] Navigate to /demos/auth
+- [ ] Verify the banner is visible with a green/success appearance (data-testid="auth-banner", data-authenticated="true")
+- [ ] Verify auth-status text reads "✓ Signed in as demo user"
+- [ ] Verify the "Sign out" button is visible and enabled (data-testid="auth-sign-out-button")
+- [ ] Verify the "Sign in" button is NOT present
+- [ ] Verify <CopilotChat /> is mounted below the banner
+- [ ] Verify no auth-demo-error surface is shown (data-testid="auth-demo-error" absent)
+- [ ] Verify no console errors on page load (the `/info` handshake should succeed)
+
+### 2. Authenticated send → assistant response
+
+- [ ] Type "Hello" and click send
+- [ ] Within 30 seconds, an assistant response is rendered in the transcript
+- [ ] No auth-demo-error surface appears
+
+### 3. Sign out flips the banner and surfaces 401 without crashing
+
+- [ ] Click "Sign out"
+- [ ] Within 1 second, the banner flips to amber/warning appearance (data-authenticated="false")
+- [ ] Verify auth-status text reads "⚠ Signed out — the agent will reject your messages until you sign in."
+- [ ] Verify the "Sign in" button is visible (data-testid="auth-authenticate-button")
+- [ ] Verify the "Sign out" button is no longer present
+- [ ] Type "Hello again" and click send
+- [ ] Within 15 seconds, the page-level error surface appears:
+  - `data-testid="auth-demo-error"` visible with text containing "401" and/or "Unauthorized"
+- [ ] Verify the banner is STILL visible — the page must not white-screen
+- [ ] Verify no assistant response appears for the unauthenticated send
+
+### 4. Sign in clears the error and restores sends
+
+- [ ] Click "Sign in"
+- [ ] Within 1 second, the banner flips back to green (data-authenticated="true")
+- [ ] Verify the auth-demo-error surface is cleared
+- [ ] Type "Hello" and click send
+- [ ] Within 30 seconds, an assistant response is rendered
+
+### 5. Refresh resets state to authenticated
+
+- [ ] Hard-reload the page
+- [ ] Banner is green on first render (default state is authenticated; state does NOT persist)
+- [ ] No error surface on first render
+
+### 6. Error Handling
+
+- [ ] With DevTools Network panel blocking /api/copilotkit-auth, send a message while authenticated
+- [ ] Verify a network-level error surfaces cleanly (no uncaught promise rejection in console)
+- [ ] Restore network; verify sends work again without a page reload
+
+## Expected Results
+
+- Page loads authenticated by default — no 401 crash on initial `/info` fetch
+- Banner state flips within 1s of Sign out / Sign in clicks
+- Post-sign-out sends produce a visible 401 error within 15s via auth-demo-error
+- Page never white-screens after sign out — banner and composer remain mounted
+- Authenticated sends produce an assistant response within 30s
+- Refresh fully resets auth state (back to authenticated)

showcase/integrations/langroid/qa/chat-customization-css.md

@@ -0,0 +1,20 @@
+# QA: Chat Customization (CSS) — Langroid
+
+## Prerequisites
+
+- Demo is deployed
+- Agent backend reachable via /api/health
+
+## Test Steps
+
+- [ ] Navigate to /demos/chat-customization-css
+- [ ] Verify the scoped wrapper `.chat-css-demo-scope` renders (DOM inspector)
+- [ ] Verify user bubble shows pink gradient (hot pink -> magenta)
+- [ ] Verify assistant bubble shows amber monospace style
+- [ ] Verify the textarea input has a dashed pink border
+- [ ] Send a message; verify styled reply appears
+
+## Expected Results
+
+- Custom theme CSS applies only inside the demo wrapper
+- Chat functions normally

showcase/integrations/langroid/qa/chat-slots.md

@@ -0,0 +1,9 @@
+# QA: Chat Slots — Langroid
+
+## Test Steps
+
+- [ ] Navigate to /demos/chat-slots
+- [ ] Verify custom welcome screen with "Welcome to the Slots demo" card renders
+- [ ] Verify custom disclaimer is visible beneath the input
+- [ ] Send a message
+- [ ] Verify the assistant reply is wrapped in the tinted "slot" card (custom-assistant-message)

showcase/integrations/langroid/qa/declarative-gen-ui.md

@@ -0,0 +1,18 @@
+# QA: Declarative Generative UI (A2UI) — Langroid
+
+## Prerequisites
+
+- Demo is deployed and accessible
+- Agent backend is healthy
+- `/api/copilotkit-declarative-gen-ui` is configured with `injectA2UITool: false`
+
+## Test Steps
+
+### 1. Basic Functionality
+
+- [ ] Navigate to `/demos/declarative-gen-ui`
+- [ ] Verify the chat interface loads in a centered full-height layout
+- [ ] Click the "Show a KPI dashboard" suggestion
+- [ ] Verify the agent's `generate_a2ui` tool-call completes
+- [ ] Verify one or more A2UI-rendered MetricCard/PieChart/BarChart surfaces
+      appear in the transcript

showcase/integrations/langroid/qa/frontend-tools-async.md

@@ -0,0 +1,9 @@
+# QA: Frontend Tools (Async) — Langroid
+
+## Test Steps
+
+- [ ] Navigate to /demos/frontend-tools-async
+- [ ] Ask "Find my notes about project planning."
+- [ ] Verify the notes-card renders with matching keyword
+- [ ] Verify the loading state shows briefly while the async handler resolves
+- [ ] Try "Search my notes for anything related to auth" and verify auth-tagged notes appear

showcase/integrations/langroid/qa/frontend-tools.md

@@ -0,0 +1,9 @@
+# QA: Frontend Tools — Langroid
+
+## Test Steps
+
+- [ ] Navigate to /demos/frontend-tools
+- [ ] Verify the background-container renders with default background
+- [ ] Ask "Change the background to a blue-to-purple gradient"
+- [ ] Verify the tool invokes the frontend handler and the background style updates
+- [ ] Verify the assistant confirms the change in chat

showcase/integrations/langroid/qa/gen-ui-agent.md

@@ -0,0 +1,62 @@
+# QA: Agentic Generative UI — Langroid
+
+## Prerequisites
+
+- Demo is deployed and accessible
+- Agent backend is healthy (check /api/health)
+
+## Test Steps
+
+### 1. Basic Functionality
+
+- [ ] Navigate to the gen-ui-agent demo page
+- [ ] Verify the chat interface loads in a centered full-height layout
+- [ ] Verify the chat input placeholder "Type a message" is visible
+- [ ] Send a basic message
+- [ ] Verify the agent responds
+
+### 2. Feature-Specific Checks
+
+#### Suggestions
+
+- [ ] Verify "Simple plan" suggestion button is visible (plan to go to Mars in 5 steps)
+- [ ] Verify "Complex plan" suggestion button is visible (plan to make pizza in 10 steps)
+
+#### Task Progress Tracker (useAgent with state streaming)
+
+- [ ] Click "Simple plan" suggestion or type "Build a plan to go to Mars in 5 steps"
+- [ ] Verify the TaskProgress component renders (`data-testid="task-progress"`)
+- [ ] Verify the progress bar appears with a gradient fill
+- [ ] Verify step items appear with descriptions (`data-testid="task-step-text"`)
+- [ ] Verify the "N/N Complete" counter updates as steps complete
+- [ ] Verify completed steps show:
+  - Green background gradient
+  - Check icon
+  - Green text color
+- [ ] Verify the current pending step shows:
+  - Blue/purple background gradient
+  - Spinner icon with "Processing..." text
+  - Pulsing animation
+- [ ] Verify future pending steps show:
+  - Gray background
+  - Clock icon
+  - Muted text color
+
+#### Complex Plan
+
+- [ ] Type "Plan to make pizza in 10 steps"
+- [ ] Verify 10 steps appear in the progress tracker
+- [ ] Verify progress bar width increases as steps complete
+
+### 3. Error Handling
+
+- [ ] Send an empty message (should be handled gracefully)
+- [ ] Verify no console errors during normal usage
+
+## Expected Results
+
+- Chat loads within 3 seconds
+- Agent responds within 10 seconds
+- Task progress tracker shows live step completion
+- Progress bar animates smoothly
+- No UI errors or broken layouts

showcase/integrations/langroid/qa/gen-ui-tool-based.md

@@ -0,0 +1,59 @@
+# QA: Tool-Based Generative UI — Langroid
+
+## Prerequisites
+
+- Demo is deployed and accessible
+- Agent backend is healthy (check /api/health)
+
+## Test Steps
+
+### 1. Basic Functionality
+
+- [ ] Navigate to the gen-ui-tool-based demo page
+- [ ] Verify the CopilotSidebar opens by default with title "Haiku Generator"
+- [ ] Verify a placeholder haiku card is displayed on the main area
+- [ ] Send a basic message via the sidebar
+- [ ] Verify the agent responds
+
+### 2. Feature-Specific Checks
+
+#### Suggestions
+
+- [ ] Verify "Nature Haiku" suggestion button is visible
+- [ ] Verify "Ocean Haiku" suggestion button is visible
+- [ ] Verify "Spring Haiku" suggestion button is visible
+
+#### Haiku Generation (useFrontendTool)
+
+- [ ] Click the "Nature Haiku" suggestion or type "Write me a haiku about nature"
+- [ ] Verify a HaikuCard renders (`data-testid="haiku-card"`) with:
+  - [ ] Three Japanese text lines (`data-testid="haiku-japanese-line"`)
+  - [ ] Three English translation lines (`data-testid="haiku-english-line"`)
+  - [ ] A background gradient style applied to the card
+- [ ] Verify the Japanese text contains actual Japanese characters (not Latin)
+- [ ] Verify the English lines are a readable English translation
+
+#### Image Display
+
+- [ ] After haiku generation, verify an image renders (`data-testid="haiku-image"`) if the agent provides an image_name
+- [ ] Verify the image src points to /images/ with a valid filename from the predefined list
+
+#### Multiple Haikus
+
+- [ ] Generate a second haiku (e.g. "Ocean Haiku")
+- [ ] Verify the new haiku card appears at the top
+- [ ] Verify the previous haiku card is still visible below
+- [ ] Verify the initial placeholder haiku is removed
+
+### 3. Error Handling
+
+- [ ] Send an empty message (should be handled gracefully)
+- [ ] Verify no console errors during normal usage
+
+## Expected Results
+
+- Sidebar loads within 3 seconds
+- Agent responds and generates haiku within 10 seconds
+- Haiku cards display with Japanese and English text
+- Generated haikus stack with newest on top
+- No UI errors or broken layouts

showcase/integrations/langroid/qa/headless-complete.md

@@ -0,0 +1,23 @@
+# QA: Headless Chat (Complete) — Langroid
+
+## Prerequisites
+
+- Demo is deployed and accessible
+- Agent backend is healthy
+
+## Test Steps
+
+### 1. Basic Functionality
+
+- [ ] Navigate to `/demos/headless-complete`
+- [ ] Verify the page loads without `<CopilotChat />` — a hand-rolled message list + input
+- [ ] Verify the input is focused and enabled
+- [ ] Send a message and verify an assistant response bubble renders
+- [ ] Verify a typing indicator appears while the agent is running
+
+### 2. Tool Rendering
+
+- [ ] Click the "Weather in Tokyo" suggestion
+- [ ] Verify a branded WeatherCard appears inline in the message list
+- [ ] Verify tool-call renderers (useRenderTool, useDefaultRenderTool) paint
+      without the built-in CopilotChat chrome

showcase/integrations/langroid/qa/headless-simple.md

@@ -0,0 +1,9 @@
+# QA: Headless Chat (Simple) — Langroid
+
+## Test Steps
+
+- [ ] Navigate to /demos/headless-simple
+- [ ] Verify heading "Headless Chat (Simple)" visible
+- [ ] Verify empty-state message "No messages yet"
+- [ ] Type a message and press Enter; verify the user bubble appears
+- [ ] Ask "show a card about cats"; verify a ShowCard renders from the useComponent registration

showcase/integrations/langroid/qa/hitl-in-app.md

@@ -0,0 +1,10 @@
+# QA: HITL In-App — Langroid
+
+## Test Steps
+
+- [ ] Navigate to /demos/hitl-in-app
+- [ ] Verify the tickets panel renders with tickets #12345, #12346, #12347
+- [ ] Ask "Please approve a $50 refund to Jordan Rivera on ticket #12345."
+- [ ] Verify an approval dialog (`approval-dialog` testid) appears OUTSIDE the chat
+- [ ] Click Approve; verify the dialog closes and the agent acknowledges the decision in chat
+- [ ] Repeat with a Reject decision

showcase/integrations/langroid/qa/hitl-in-chat.md

@@ -0,0 +1,57 @@
+# QA: Human in the Loop — Langroid
+
+## Prerequisites
+
+- Demo is deployed and accessible
+- Agent backend is healthy (check /api/health)
+
+## Test Steps
+
+### 1. Basic Functionality
+
+- [ ] Navigate to the HITL demo page (`/demos/hitl`) > _Note: the URL path `/demos/hitl` is intentionally shorter than the feature id `hitl-in-chat`._
+- [ ] Verify the chat interface loads in a centered max-w-4xl container
+- [ ] Verify the chat input placeholder "Type a message" is visible
+- [ ] Send a basic message
+- [ ] Verify the agent responds
+
+### 2. Feature-Specific Checks
+
+#### Suggestions
+
+- [ ] Verify "Simple plan" suggestion button is visible
+- [ ] Verify "Complex plan" suggestion button is visible
+- [ ] Click the "Simple plan" suggestion
+- [ ] Verify it triggers a message about planning a trip to Mars in 5 steps
+
+#### Step Selection and Approval
+
+The HITL demo renders a single StepSelector card regardless of whether
+the underlying flow uses an interrupt hook or a frontend HITL tool. The
+framework-specific hook name is an implementation detail covered in each
+package's demo source; QA below validates the user-visible card behavior.
+
+- [ ] Send "Plan a trip to Mars in 5 steps"
+- [ ] Verify the StepSelector card appears (`data-testid="select-steps"`)
+- [ ] Verify step items are displayed with checkboxes (`data-testid="step-item"`)
+- [ ] Verify step text is visible (`data-testid="step-text"`)
+- [ ] Verify the selected count display shows "N/N selected"
+- [ ] Toggle a step checkbox off and verify the count decreases
+- [ ] Toggle it back on and verify the count increases
+- [ ] Click "Perform Steps (N)" / "Confirm (N)" button
+- [ ] Verify the agent continues processing after confirmation
+- [ ] In a new conversation, trigger the same flow and click "Reject" (where present)
+- [ ] Verify the card reflects the decision (Accepted / Rejected) and buttons disable
+
+### 3. Error Handling
+
+- [ ] Send an empty message (should be handled gracefully)
+- [ ] Verify no console errors during normal usage
+
+## Expected Results
+
+- Chat loads within 3 seconds
+- Agent responds within 10 seconds
+- Step selector renders with toggleable checkboxes
+- Accept/Reject flow completes without errors
+- No UI errors or broken layouts

showcase/integrations/langroid/qa/prebuilt-popup.md

@@ -0,0 +1,9 @@
+# QA: Prebuilt Popup — Langroid
+
+## Test Steps
+
+- [ ] Navigate to /demos/prebuilt-popup
+- [ ] Verify the floating launcher bubble renders
+- [ ] Verify the popup opens by default showing "Ask the popup anything..." placeholder
+- [ ] Send a message and verify reply
+- [ ] Close and reopen the popup via the launcher

showcase/integrations/langroid/qa/prebuilt-sidebar.md

@@ -0,0 +1,9 @@
+# QA: Prebuilt Sidebar — Langroid
+
+## Test Steps
+
+- [ ] Navigate to /demos/prebuilt-sidebar
+- [ ] Verify main content heading "Sidebar demo" visible
+- [ ] Verify sidebar docked on the side, open by default
+- [ ] Send "hi" and verify agent responds
+- [ ] Click the launcher to collapse/expand the sidebar

showcase/integrations/langroid/qa/readonly-state-agent-context.md

@@ -0,0 +1,10 @@
+# QA: Readonly State (Agent Context) — Langroid
+
+## Test Steps
+
+- [ ] Navigate to /demos/readonly-state-agent-context
+- [ ] Verify the context card renders with default Name "Atai"
+- [ ] Change Name to "Jordan", verify published JSON updates
+- [ ] Toggle recent-activity checkboxes, verify JSON updates
+- [ ] Ask "What do you know about me?" — agent should reference the context values
+- [ ] Change timezone, ask "What time is it for me?" — agent should reflect the new zone

showcase/integrations/langroid/qa/reasoning-default-render.md

@@ -0,0 +1,13 @@
+# QA: Reasoning (Default Render) — Langroid
+
+NOTE: The Langroid AG-UI adapter does not currently emit
+`REASONING_MESSAGE_*` events, so no reasoning block will appear. This
+demo proves the zero-config default render path compiles and renders; it
+will show reasoning automatically once the adapter forwards thinking
+events.
+
+## Test Steps
+
+- [ ] Navigate to /demos/reasoning-default-render
+- [ ] Verify chat input is visible
+- [ ] Send "hello"; verify the agent replies

showcase/integrations/langroid/qa/shared-state-read-write.md

@@ -0,0 +1,62 @@
+# QA: Shared State (Read + Write) — Langroid
+
+## Prerequisites
+
+- Demo is deployed and accessible at `/demos/shared-state-read-write` on the dashboard host
+- Agent backend is healthy (`/api/health`); `OPENAI_API_KEY` is set on Railway; the FastAPI agent server exposes `POST /shared-state-read-write` (see `src/agent_server.py`)
+
+## Test Steps
+
+### 1. Basic Functionality
+
+- [ ] Navigate to `/demos/shared-state-read-write`; verify the page renders within 3s with the left sidebar (preferences + notes cards) and the right-side `CopilotChat` pane
+- [ ] Verify `data-testid="preferences-card"` is visible with heading "Your preferences"
+- [ ] Verify `data-testid="notes-card"` is visible with heading "Agent notes" and empty-state `data-testid="notes-empty"` reading "No notes yet. Ask the agent to remember something."
+- [ ] Verify the chat input placeholder is "Chat with the agent..."
+- [ ] Verify all 3 suggestion pills are visible with verbatim titles: "Greet me", "Remember something", "Plan a weekend"
+- [ ] Send "Hello" and verify an assistant text response appears within 10s
+
+### 2. Feature-Specific Checks
+
+#### UI Writes -> Agent Reads (preferences via `agent.setState`)
+
+- [ ] Type "Atai" into `data-testid="pref-name"`; verify `data-testid="pref-state-json"` updates to include `"name": "Atai"`
+- [ ] Change `data-testid="pref-tone"` to `formal`; verify the JSON preview reflects `"tone": "formal"`
+- [ ] Change `data-testid="pref-language"` to `Spanish`; verify the JSON preview reflects `"language": "Spanish"`
+- [ ] Click the `Cooking` and `Travel` interest pills; verify both show the selected style (border `#BEC2FF`, bg `#BEC2FF1A`) and the JSON preview's `interests` array contains both entries
+- [ ] Send "What do you know about me?"; verify within 10s the assistant reply references the name "Atai", a formal tone, Spanish, and the Cooking/Travel interests (the Langroid handler injects these into the system prompt each turn — see `build_preferences_system_message` in `src/agents/shared_state_read_write.py`)
+- [ ] Click the "Plan a weekend" suggestion; verify the reply is tailored to the selected interests
+
+#### Agent Writes -> UI Reads (notes via `set_notes` tool)
+
+- [ ] Click the "Remember something" suggestion (sends "Remember that I prefer morning meetings and that I don't eat dairy.")
+- [ ] Within 15s verify `data-testid="notes-list"` appears in the notes card and contains at least 2 `data-testid="note-item"` entries mentioning "morning meetings" and "dairy"
+- [ ] Verify `data-testid="notes-empty"` is no longer rendered
+- [ ] Send "Also remember I live in Berlin."; verify within 15s the notes list grows (previous notes preserved, new note added) — confirms the agent passes the FULL updated list per `set_notes` contract
+
+#### UI Writes Back to Agent-Authored Slice (clear notes)
+
+- [ ] With notes present, verify `data-testid="notes-clear-button"` is visible
+- [ ] Click the Clear button; verify the notes list disappears and `data-testid="notes-empty"` re-renders
+- [ ] Ask "What do you remember about me?"; verify the agent no longer cites the cleared notes (state was written back by the UI via `agent.setState({ notes: [] })`)
+
+#### Multi-Turn State Persistence
+
+- [ ] Change tone to `playful` and add the `Music` interest; send "Write me a one-line haiku greeting."; verify the reply is playful and references music
+- [ ] Send a follow-up "Do it again in French."; verify the reply remains playful, switches to French, and still acknowledges the music interest — confirms preferences persist across turns without being re-sent
+- [ ] Reload the page; verify preferences reset to defaults (`tone: casual`, `language: English`, empty interests, empty name) and notes reset to empty (state is per-session, seeded by the page's `useEffect`)
+
+### 3. Error Handling
+
+- [ ] Attempt to send an empty message; verify it is a no-op (no user bubble, no assistant response)
+- [ ] Deselect all interests and clear the name; send "Who am I?"; verify the agent answers without crashing (handler skips injection when `preferences` is empty)
+- [ ] Verify DevTools -> Console shows no uncaught errors during any flow above
+- [ ] Hit `GET /api/copilotkit-shared-state-read-write` (or the dashboard's health surface) — should not error; the route only exposes POST but should not 500 on accidental GETs (Next.js will return its standard 405)
+
+## Expected Results
+
+- Page loads within 3 seconds; assistant text response within 10 seconds
+- Preferences writes are reflected in `pref-state-json` synchronously on change
+- Agent-authored notes appear in `notes-card` within 15 seconds of a "remember" prompt, and the full prior list is preserved on subsequent `set_notes` calls
+- Clear button round-trips UI -> agent state and the agent loses access to the cleared notes on the next turn
+- No UI layout breaks, no uncaught console errors

showcase/integrations/langroid/qa/shared-state-read.md

@@ -0,0 +1,75 @@
+# QA: Shared State (Reading) — Langroid
+
+## Prerequisites
+
+- Demo is deployed and accessible
+- Agent backend is healthy (check /api/health)
+
+## Test Steps
+
+### 1. Basic Functionality
+
+- [ ] Navigate to the shared-state-read demo page
+- [ ] Verify the recipe card form loads (`data-testid="recipe-card"`)
+- [ ] Verify the CopilotSidebar opens by default with title "AI Recipe Assistant"
+- [ ] Send a message via the sidebar
+- [ ] Verify the agent responds
+
+### 2. Feature-Specific Checks
+
+#### Initial Recipe State
+
+- [ ] Verify the recipe title input shows "Make Your Recipe"
+- [ ] Verify the cooking time dropdown defaults to "45 min"
+- [ ] Verify the skill level dropdown defaults to "Intermediate"
+- [ ] Verify the default ingredients are displayed:
+  - [ ] Carrots (3 large, grated) with carrot emoji
+  - [ ] All-Purpose Flour (2 cups) with wheat emoji
+- [ ] Verify the default instruction is displayed: "Preheat oven to 350 F"
+
+#### Suggestions
+
+- [ ] Verify "Create Italian recipe" suggestion is visible
+- [ ] Verify "Make it healthier" suggestion is visible
+- [ ] Verify "Suggest variations" suggestion is visible
+
+#### Recipe Editing (Local State)
+
+- [ ] Edit the recipe title and verify it updates
+- [ ] Change the skill level dropdown and verify it updates
+- [ ] Change the cooking time dropdown and verify it updates
+- [ ] Toggle a dietary preference checkbox (e.g. "Vegetarian") and verify it's checked
+- [ ] Click "+ Add Ingredient" (`data-testid="add-ingredient-button"`) and verify a new empty row appears
+- [ ] Edit an ingredient name and amount
+- [ ] Remove an ingredient by clicking the "x" button
+- [ ] Click "+ Add Step" and verify a new instruction row appears
+- [ ] Edit an instruction and verify it saves
+- [ ] Remove an instruction by clicking the "x" button
+
+#### AI-Powered Recipe Updates (useAgent with shared state)
+
+- [ ] Click "Create Italian recipe" suggestion
+- [ ] Verify the agent updates the recipe title, ingredients, and instructions
+- [ ] Verify the ping indicator appears on changed sections
+- [ ] Verify the "Improve with AI" button (`data-testid="improve-button"`) changes to "Please Wait..." while loading
+- [ ] Click "Improve with AI" and verify the recipe is enhanced
+
+#### Agent Reads Frontend State
+
+- [ ] Edit the recipe (change title, add ingredients)
+- [ ] Ask the agent "What recipe am I making?"
+- [ ] Verify the agent's response references the current recipe state
+
+### 3. Error Handling
+
+- [ ] Send an empty message (should be handled gracefully)
+- [ ] Verify no console errors during normal usage
+- [ ] Verify the "Improve with AI" button is disabled while loading
+
+## Expected Results
+
+- Recipe card and sidebar load within 3 seconds
+- Agent responds within 10 seconds
+- Recipe state syncs bidirectionally between UI and agent
+- Ping indicators highlight changed sections
+- No UI errors or broken layouts

showcase/integrations/langroid/qa/shared-state-streaming.md

@@ -0,0 +1,41 @@
+# QA: State Streaming — Langroid
+
+## Prerequisites
+
+- Demo is deployed and accessible
+- Agent backend is healthy (check /api/health)
+
+## Test Steps
+
+### 1. Basic Functionality
+
+- [ ] Navigate to the shared-state-streaming demo page
+- [ ] Verify the chat interface loads with title "State Streaming"
+- [ ] Verify the chat input placeholder "Type a message..." is visible
+- [ ] Send a basic message (e.g. "Hello! What can you do?")
+- [ ] Verify the agent responds
+
+### 2. Feature-Specific Checks
+
+#### Suggestions
+
+- [ ] Verify "Get started" suggestion button is visible
+
+#### Note: Stub Demo
+
+> **Status: Stub** — This demo is currently a stub (TODO: implement)
+
+- [ ] Verify the basic CopilotChat loads and accepts messages
+- [ ] Verify the agent responds to messages
+- [ ] No custom UI components are expected beyond the chat interface
+
+### 3. Error Handling
+
+- [ ] Send an empty message (should be handled gracefully)
+- [ ] Verify no console errors during normal usage
+
+## Expected Results
+
+- Chat loads within 3 seconds
+- Agent responds within 10 seconds
+- No UI errors or broken layouts

showcase/integrations/langroid/qa/shared-state-write.md

@@ -0,0 +1,41 @@
+# QA: Shared State (Writing) — Langroid
+
+## Prerequisites
+
+- Demo is deployed and accessible
+- Agent backend is healthy (check /api/health)
+
+## Test Steps
+
+### 1. Basic Functionality
+
+- [ ] Navigate to the shared-state-write demo page
+- [ ] Verify the chat interface loads with title "Shared State (Writing)"
+- [ ] Verify the chat input placeholder "Type a message..." is visible
+- [ ] Send a basic message (e.g. "Hello! What can you do?")
+- [ ] Verify the agent responds
+
+### 2. Feature-Specific Checks
+
+#### Suggestions
+
+- [ ] Verify "Get started" suggestion button is visible
+
+#### Note: Stub Demo
+
+> **Status: Stub** — This demo is currently a stub (TODO: implement)
+
+- [ ] Verify the basic CopilotChat loads and accepts messages
+- [ ] Verify the agent responds to messages
+- [ ] No custom UI components are expected beyond the chat interface
+
+### 3. Error Handling
+
+- [ ] Send an empty message (should be handled gracefully)
+- [ ] Verify no console errors during normal usage
+
+## Expected Results
+
+- Chat loads within 3 seconds
+- Agent responds within 10 seconds
+- No UI errors or broken layouts

showcase/integrations/langroid/qa/subagents.md

@@ -0,0 +1,56 @@
+# QA: Sub-Agents — Langroid
+
+## Prerequisites
+
+- Demo is deployed and accessible at `/demos/subagents` on the dashboard host
+- Agent backend is healthy (`/api/health`); `OPENAI_API_KEY` is set on Railway; the FastAPI agent server exposes `POST /subagents` (see `src/agent_server.py`)
+
+## Test Steps
+
+### 1. Basic Functionality
+
+- [ ] Navigate to `/demos/subagents`; verify the page renders within 3s with the delegation log on the left and the `CopilotChat` pane on the right
+- [ ] Verify `data-testid="delegation-log"` is visible with header "Sub-agent delegations"
+- [ ] Verify `data-testid="delegation-count"` shows `0 calls`
+- [ ] Verify the empty-state copy "Ask the supervisor to complete a task. Every sub-agent it calls will appear here." is rendered
+- [ ] Verify the chat input placeholder is "Give the supervisor a task..."
+- [ ] Verify all 3 suggestion pills are visible with verbatim titles: "Write a blog post", "Explain a topic", "Summarize a topic"
+
+### 2. Feature-Specific Checks
+
+#### Live delegation log (running -> completed)
+
+- [ ] Click the "Write a blog post" suggestion (sends a multi-step request that should trigger research -> write -> critique)
+- [ ] Within 5s verify `data-testid="supervisor-running"` ("Supervisor running" pill) appears in the log header
+- [ ] Within 10s verify the first `data-testid="delegation-entry"` appears with the Research badge (`🔎 Research`) and `running` status; the result body should show "Sub-agent running…"
+- [ ] Within 30s verify the entry flips to `completed` status and a bulleted list of facts is rendered in the result body
+- [ ] Verify a second `data-testid="delegation-entry"` appears with the Writing badge (`✍️ Writing`), goes through `running` -> `completed`, and renders a 1-paragraph draft
+- [ ] Verify a third `data-testid="delegation-entry"` appears with the Critique badge (`🧐 Critique`) and renders 2-3 critiques
+- [ ] Verify `data-testid="delegation-count"` updates to `3 calls` (or more if the supervisor delegates again)
+- [ ] After the run finishes, verify `data-testid="supervisor-running"` is no longer rendered and the chat receives a brief final summary
+
+#### Sequential chaining
+
+- [ ] Send "Explain how large language models handle tool calling. Research, write a paragraph, then critique."
+- [ ] Verify the delegations appear in order: Research, then Writing, then Critique (the supervisor passes the prior step's output through `task`)
+- [ ] Verify each entry's `Task:` line references the user's topic and (for Writing/Critique) cites the prior step
+
+#### Multi-message persistence
+
+- [ ] After a completed run, send another task ("Summarize a topic …")
+- [ ] Verify NEW delegation entries are appended to the log (existing entries from the prior turn remain visible, count grows)
+- [ ] Reload the page; verify the delegation log resets to empty and `data-testid="delegation-count"` shows `0 calls`
+
+### 3. Error Handling
+
+- [ ] Send a trivially-conversational message like "Hi"; verify the supervisor either responds in plain text without delegating (count stays at `0 calls`) or delegates only once and finishes — no infinite loop
+- [ ] Verify DevTools -> Console shows no uncaught errors during any flow above
+- [ ] If the secondary LLM fails (e.g. quota exhausted), verify a `failed` delegation entry is rendered with red status and a brief error message in the result body — the supervisor still produces a final user-facing message
+
+## Expected Results
+
+- Page loads within 3 seconds
+- Each delegation transitions from `running` to `completed` (or `failed`) within ~30s
+- Delegation log entries appear in submission order and preserve across multiple supervisor turns within a single run
+- The supervisor returns a final natural-language summary after the last sub-agent completes
+- No UI layout breaks, no uncaught console errors

showcase/integrations/langroid/qa/tool-rendering-custom-catchall.md

@@ -0,0 +1,35 @@
+# QA: Tool Rendering (Custom Catch-all) — Langroid
+
+## Prerequisites
+
+- Demo is deployed and accessible
+- Agent backend is healthy (check /api/health)
+- Agent slug `tool-rendering-custom-catchall` is registered at `/api/copilotkit`
+
+## Test Steps
+
+### 1. Basic Functionality
+
+- [ ] Navigate to the `tool-rendering-custom-catchall` demo page
+- [ ] Verify the chat interface loads in a centered full-height layout
+
+### 2. Feature-Specific Checks — Custom Wildcard Renderer
+
+The page registers a single branded wildcard via `useDefaultRenderTool`
+with a custom `render` function (`CustomCatchallRenderer`). Every tool
+call paints through that same branded card.
+
+- [ ] Click "Weather in SF"
+- [ ] Verify a card with `data-testid="custom-catchall-card"` appears
+- [ ] Verify `data-testid="custom-catchall-tool-name"` reads `get_weather`
+- [ ] Verify `data-testid="custom-catchall-status"` transitions through
+      `streaming` / `running` and lands on `done`
+- [ ] Expand Arguments and verify the args JSON is visible
+- [ ] Expand Result and verify the mock weather payload is visible
+- [ ] Verify NO built-in default card shows for this tool
+
+### 3. Expected
+
+- Every tool paints through the same branded card
+- No per-tool renderers
+- Status badge matches tool lifecycle

showcase/integrations/langroid/qa/tool-rendering-default-catchall.md

@@ -0,0 +1,47 @@
+# QA: Tool Rendering (Default Catch-all) — Langroid
+
+## Prerequisites
+
+- Demo is deployed and accessible
+- Agent backend is healthy (check /api/health)
+- Agent slug `tool-rendering-default-catchall` is registered at `/api/copilotkit`
+
+## Test Steps
+
+### 1. Basic Functionality
+
+- [ ] Navigate to the `tool-rendering-default-catchall` demo page
+- [ ] Verify the chat interface loads in a centered full-height layout (max-width 4xl, `rounded-2xl`)
+- [ ] Verify the chat input placeholder "Type a message" is visible
+- [ ] Send a basic message and verify the Langroid agent responds
+
+### 2. Feature-Specific Checks — Built-in Default Tool-Call UI
+
+The page calls `useDefaultRenderTool()` with NO config, so every tool
+call routes to CopilotKit's built-in `DefaultToolCallRenderer`.
+
+#### Suggestions
+
+- [ ] Verify "Weather in SF" suggestion pill is visible
+- [ ] Verify "Find flights" suggestion pill is visible
+- [ ] Verify "Weather in Tokyo" suggestion pill is visible
+
+#### get_weather renders via the built-in default card
+
+- [ ] Click "Weather in SF"
+- [ ] Verify a default tool-call card appears with `get_weather` as header
+- [ ] Verify status transitions `Running -> Done`
+- [ ] Verify no `data-testid="custom-catchall-card"` and no
+      `data-testid="weather-card"` — only the built-in card paints.
+
+#### search_flights renders via the same built-in card
+
+- [ ] Click "Find flights"
+- [ ] Verify a second default card with `search_flights` header
+- [ ] Verify status lands on `Done`
+
+### 3. Expected
+
+- No per-tool branded cards
+- No custom wildcard renderer
+- Every tool call uses the package-provided default card

showcase/integrations/langroid/qa/tool-rendering.md

@@ -0,0 +1,61 @@
+# QA: Tool Rendering — Langroid
+
+## Prerequisites
+
+- Demo is deployed and accessible
+- Agent backend is healthy (check /api/health)
+
+## Test Steps
+
+### 1. Basic Functionality
+
+- [ ] Navigate to the tool-rendering demo page
+- [ ] Verify the chat interface loads in a centered full-height layout
+- [ ] Verify the chat input placeholder "Type a message" is visible
+- [ ] Send a basic message
+- [ ] Verify the agent responds
+
+### 2. Feature-Specific Checks
+
+#### Suggestions
+
+- [ ] Verify "Weather in San Francisco" suggestion button is visible
+- [ ] Verify "Weather in New York" suggestion button is visible
+- [ ] Verify "Weather in Tokyo" suggestion button is visible
+- [ ] Click a weather suggestion and verify it populates the input or sends the message
+
+#### Weather Card Rendering (useRenderTool)
+
+- [ ] Type "What's the weather in San Francisco?"
+- [ ] Verify loading state shows "Retrieving weather..." with a spinner
+- [ ] Verify the WeatherCard renders (`data-testid="weather-card"`) with:
+  - [ ] City name displayed (`data-testid="weather-city"`)
+  - [ ] Temperature in both Celsius and Fahrenheit
+  - [ ] Humidity percentage (`data-testid="weather-humidity"`)
+  - [ ] Wind speed in mph (`data-testid="weather-wind"`)
+  - [ ] Feels-like temperature (`data-testid="weather-feels-like"`)
+  - [ ] Conditions text with appropriate weather icon (sun/rain/cloud)
+- [ ] Verify the card background color matches the weather condition theme:
+  - Clear/Sunny: #667eea (blue-purple)
+  - Rain/Storm: #4A5568 (dark gray)
+  - Cloudy: #718096 (medium gray)
+  - Snow: #63B3ED (light blue)
+
+#### Multiple Weather Queries
+
+- [ ] Ask about weather in a second city
+- [ ] Verify a second WeatherCard renders without breaking the first
+- [ ] Verify each card shows the correct city name
+
+### 3. Error Handling
+
+- [ ] Send an empty message (should be handled gracefully)
+- [ ] Verify no console errors during normal usage
+
+## Expected Results
+
+- Chat loads within 3 seconds
+- Agent responds within 10 seconds
+- Weather cards render with all data fields populated
+- Weather icon and theme color match the conditions
+- No UI errors or broken layouts