chore(showcase/packages): QA markdown parity + integration tooling

Rename hitl.md → hitl-in-chat.md across all 17 showcase packages,
add shared-state-read / shared-state-write / shared-state-streaming /
gen-ui-agent / subagents QA docs where missing, update demos/hitl
README cross-links. Refresh showcase/shell + shell-dojo registry +
demo-content JSON to match new QA shape. Update integration tooling
(audit, create-integration, bundle-demo-content, generate-registry,
validate-parity, capture-previews, manifest lib) + e2e tests to the
new parity contract.

Author: jpr5

showcase/packages/ag2/qa/hitl.md showcase/packages/ag2/qa/hitl-in-chat.mdshowcase/packages/ag2/qa/hitl.md renamed to showcase/packages/ag2/qa/hitl-in-chat.md

@@ -9,7 +9,7 @@
 
 ### 1. Basic Functionality
 
-- [ ] Navigate to the hitl demo page
+- [ ] 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
@@ -24,7 +24,12 @@
 - [ ] Click the "Simple plan" suggestion
 - [ ] Verify it triggers a message about planning a trip to Mars in 5 steps
 
-#### LangGraph Interrupt (useLangGraphInterrupt)
+#### 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"`)
@@ -33,18 +38,10 @@
 - [ ] 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)" button
+- [ ] Click "Perform Steps (N)" / "Confirm (N)" button
 - [ ] Verify the agent continues processing after confirmation
-
-#### Human-in-the-Loop Feedback (useHumanInTheLoop)
-
-- [ ] Trigger a task that generates steps via the generate_task_steps tool
-- [ ] Verify the "Review Steps" card appears (`data-testid="select-steps"`)
-- [ ] Verify Accept and Reject buttons are visible
-- [ ] Click "Confirm (N)" and verify the card shows "Accepted" status
-- [ ] In a new conversation, trigger the same flow and click "Reject"
-- [ ] Verify the card shows "Rejected" status
-- [ ] Verify buttons are disabled after a decision is made
+- [ ] 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
 

showcase/packages/ag2/qa/shared-state-streaming.md

@@ -23,7 +23,8 @@
 
 #### Note: Stub Demo
 
-- [ ] This demo is currently a stub (TODO: implement)
+> **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

showcase/packages/ag2/qa/shared-state-write.md

@@ -23,7 +23,8 @@
 
 #### Note: Stub Demo
 
-- [ ] This demo is currently a stub (TODO: implement)
+> **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

showcase/packages/ag2/qa/subagents.md

@@ -23,7 +23,8 @@
 
 #### Note: Stub Demo
 
-- [ ] This demo is currently a stub (TODO: implement)
+> **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

showcase/packages/ag2/src/app/demos/hitl/README.md

@@ -2,27 +2,27 @@
 
 ## What This Demo Shows
 
-User approves agent actions before execution
+Interactive components from the agent; user approves actions from within the chat
 
 ## How to Interact
 
 Try asking your Copilot to:
 
-- "Change the background color to a warm sunset gradient"
-- "Set the theme to dark mode"
-- "Make the background a calming blue-green gradient"
+- "Plan a trip to Mars in 5 steps"
+- "Please plan a pasta dish in 10 steps"
+- "Draft a product launch checklist in 7 steps"
 
-When the agent proposes an action, you'll see an approval prompt. Click **Approve** to let it proceed or **Reject** to cancel.
+The agent proposes a plan as a **StepSelector** card with a checkbox per step. Toggle individual steps on or off (the selected count updates as "N/N selected"), then click **Perform Steps (N)** / **Confirm (N)** to approve, or **Reject** to cancel. The card reflects the final decision ("Accepted" / "Rejected") and disables its buttons afterward.
 
 ## Technical Details
 
 What's happening technically:
 
-- **Human-in-the-Loop (HITL)** lets the agent propose actions that require user approval before execution
-- The agent calls a tool (like `change_background`), and CopilotKit intercepts it to show a confirmation dialog
-- `useHumanInTheLoop` registers a frontend tool with `requireConfirmation: true`, adding the approval step
-- The user sees what the agent wants to do (with the proposed arguments) and can approve or reject
-- This pattern is essential for high-stakes actions — database writes, API calls, or any irreversible operation
+- **Human-in-the-Loop (HITL)** lets the agent pause and hand control back to the user to review a proposed plan before continuing
+- The agent calls a tool (e.g. `generate_task_steps`) whose payload is a list of steps; the frontend renders a **StepSelector** card rather than executing immediately
+- `useHumanInTheLoop` (frontend-tool flow) or `useLangGraphInterrupt` (interrupt flow) registers a `render` that receives `{ args, respond, status }` — the StepSelector keeps local state for which steps are enabled and calls `respond({ accepted, steps })` on Confirm / Reject (CopilotKit v2 API; existing showcase packages use v1 `useLangGraphInterrupt` for the interrupt-flow demo alongside v2 hooks like `useHumanInTheLoop` — new integrations generated by `create-integration` default to the v2 `useInterrupt`.)
+- The card exposes per-step checkboxes, a live "N/N selected" count, and Confirm / Reject buttons; after a decision the buttons disable and the card shows "Accepted" or "Rejected" so the outcome is auditable in the transcript
+- This pattern is essential for plan-style flows — multi-step actions where the user needs to curate, edit, or veto what the agent is about to do before any of it runs
 
 ## Building With This
 

…claude-sdk-python/tests/e2e/hitl.spec.ts …kages/ag2/tests/e2e/hitl-in-chat.spec.tsshowcase/packages/claude-sdk-python/tests/e2e/hitl.spec.ts renamed to showcase/packages/ag2/tests/e2e/hitl-in-chat.spec.ts showcase/packages/claude-sdk-python/tests/e2e/hitl.spec.ts renamed to showcase/packages/ag2/tests/e2e/hitl-in-chat.spec.ts

@@ -14,7 +14,9 @@ test.describe("Human in the Loop", () => {
     await input.fill("Hello");
     await input.press("Enter");
 
-    await expect(page.locator('[data-role="assistant"]').first()).toBeVisible({
+    await expect(
+      page.locator(".copilotKitAssistantMessage").first(),
+    ).toBeVisible({
       timeout: 30000,
     });
   });
@@ -26,7 +28,8 @@ test.describe("Human in the Loop", () => {
     );
     await input.press("Enter");
 
-    // Either the LangGraph interrupt StepSelector or the HITL StepsFeedback should appear
+    // The HITL demo surfaces a single StepSelector card regardless of whether the
+    // underlying flow is an interrupt hook or a frontend HITL tool — assert on that.
     const stepSelector = page.locator('[data-testid="select-steps"]');
     await expect(stepSelector.first()).toBeVisible({ timeout: 60000 });
 
@@ -77,8 +80,10 @@ test.describe("Human in the Loop", () => {
     await expect(actionBtn.first()).toBeVisible({ timeout: 5000 });
     await actionBtn.first().click();
 
-    // After approval, agent should continue — look for accepted/confirmed state
-    const confirmed = page.locator("text=/Accepted|Confirmed|selected/i");
-    await expect(confirmed.first()).toBeVisible({ timeout: 10000 });
+    // After approval, the step selector's action button should disappear
+    // (StepSelector unmounts after onConfirm; StepsFeedback replaces buttons with
+    // the "Accepted" or "Rejected" banner). Assert on a post-click transition
+    // that does NOT match the pre-click "N/N selected" counter text.
+    await expect(actionBtn.first()).not.toBeVisible({ timeout: 10000 });
   });
 });

showcase/packages/ag2/tsconfig.tsbuildinfo

@@ -0,0 +1,62 @@
+# QA: Agentic Generative UI — Agno
+
+## 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/packages/agno/qa/gen-ui-agent.md

@@ -9,7 +9,7 @@
 
 ### 1. Basic Functionality
 
-- [ ] Navigate to the hitl demo page
+- [ ] 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
@@ -24,7 +24,12 @@
 - [ ] Click the "Simple plan" suggestion
 - [ ] Verify it triggers a message about planning a trip to Mars in 5 steps
 
-#### LangGraph Interrupt (useLangGraphInterrupt)
+#### 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"`)
@@ -33,18 +38,10 @@
 - [ ] 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)" button
+- [ ] Click "Perform Steps (N)" / "Confirm (N)" button
 - [ ] Verify the agent continues processing after confirmation
-
-#### Human-in-the-Loop Feedback (useHumanInTheLoop)
-
-- [ ] Trigger a task that generates steps via the generate_task_steps tool
-- [ ] Verify the "Review Steps" card appears (`data-testid="select-steps"`)
-- [ ] Verify Accept and Reject buttons are visible
-- [ ] Click "Confirm (N)" and verify the card shows "Accepted" status
-- [ ] In a new conversation, trigger the same flow and click "Reject"
-- [ ] Verify the card shows "Rejected" status
-- [ ] Verify buttons are disabled after a decision is made
+- [ ] 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
 

showcase/packages/agno/qa/hitl.md showcase/packages/agno/qa/hitl-in-chat.mdshowcase/packages/agno/qa/hitl.md renamed to showcase/packages/agno/qa/hitl-in-chat.md

@@ -0,0 +1,75 @@
+# QA: Shared State (Reading) — Agno
+
+## 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