Researched: 2026-04-07 Domain: React frontend refactoring + FastAPI backend endpoint + i18n Confidence: HIGH

Phase 15 is a frontend-heavy refactoring phase that transforms the HCP Profile Editor's tab structure to align with Azure AI Foundry's Agent editing experience. The core work involves: (1) removing two placeholder tabs (Knowledge, Tools), (2) rebuilding the Voice & Avatar tab as a two-panel Agent configuration center with left-side controls and right-side Playground preview, and (3) adding a new backend endpoint to preview auto-generated instructions.

The codebase already has nearly all building blocks in place. The VL Instance Editor page (vl-instance-editor.tsx) implements a nearly identical Playground pattern with AvatarView, AudioOrb, useVoiceLive, useAvatarStream, useAudioHandler, and transcript display. The VoiceLiveModelSelect component provides tiered model selection. The build_agent_instructions function in agent_sync_service.py handles instruction generation with override priority. The only net-new backend work is a preview endpoint that calls build_agent_instructions with profile form data and returns the generated text.

Primary recommendation: Extract the Playground preview panel from vl-instance-editor.tsx into a reusable component, then compose the new Voice & Avatar tab as a left-right split layout importing existing components (VoiceLiveModelSelect, VL Instance selector, Instructions textarea, and the new Playground panel).

<user_constraints>

• Tab structure: remove Knowledge and Tools tabs, keep Profile and Voice & Avatar only
• Voice & Avatar tab left panel: Model Deployment selector, Voice Mode toggle + VL Instance selector, Instructions area (auto-generate + editable override), Knowledge & Tools inline config
• Voice & Avatar tab right panel: Playground preview (avatar/audio orb + Start button + transcript)
• Backend: to_prompt_dict() must include agent_instructions_override; new GET endpoint for instructions preview
• i18n: new keys for model deployment, voice mode toggle, instructions area (en-US + zh-CN)

• Knowledge & Tools inline section UI component details
• Playground audio orb animation effect
• Instructions auto-generation API call timing (realtime vs on-demand)

• Knowledge area full file upload functionality (UI skeleton only, backend integration later)
• Tools area full Function Call configuration (UI skeleton only)
• Playground full real-time conversation functionality (UI structure + Start button first) </user_constraints>

<phase_requirements>

Installation: No new packages required. This phase only uses existing dependencies. [VERIFIED: codebase analysis]

frontend/src/
├── pages/admin/
│   └── hcp-profile-editor.tsx       # Modified: remove Knowledge/Tools tabs
├── components/admin/
│   ├── voice-avatar-tab.tsx          # REWRITE: 2-panel agent config center
│   ├── agent-config-left-panel.tsx   # NEW: left panel (model, voice mode, instructions)
│   ├── playground-preview-panel.tsx  # NEW: right panel (avatar/orb + start + transcript)
│   └── instructions-section.tsx      # NEW: auto-gen + override + magic wand
├── hooks/
│   └── use-hcp-profiles.ts           # Modified: add usePreviewInstructions hook
└── api/
    └── hcp-profiles.ts               # Modified: add previewInstructions API call

What: Voice & Avatar tab uses CSS Grid with grid-cols-1 lg:grid-cols-2 for responsive left-right split. When to use: Admin editor pages that need both configuration controls and live preview. Example:

// Source: existing pattern from vl-instance-editor.tsx
<div className="grid grid-cols-1 lg:grid-cols-2 gap-6">
  <div className="space-y-4"> {/* Left: Config controls */}
    <AgentConfigLeftPanel />
  </div>
  <div className="sticky top-4"> {/* Right: Playground preview */}
    <PlaygroundPreviewPanel />
  </div>
</div>

What: Display auto-generated instructions text, allow user to type an override, provide magic wand button to re-generate. When to use: When system prompt is derived from structured data but users may want customization. Backend flow:

# Source: agent_sync_service.py build_agent_instructions() [VERIFIED: codebase]
# 1. If agent_instructions_override is non-empty -> return override
# 2. Otherwise -> format DEFAULT_AGENT_TEMPLATE with profile data

Frontend flow:

1. On tab load, call GET /api/v1/hcp-profiles/{id}/preview-instructions to get auto-generated text
2. Show in read-only textarea (collapsed/dimmed when override is active)
3. Override textarea bound to agent_instructions_override form field
4. Magic wand button: re-call preview endpoint, show result in auto-gen area

What: Extract test session logic from vl-instance-editor.tsx into a reusable Playground component. Why: The VL Instance Editor page (lines 248-367) already implements the complete pattern: useVoiceLive + useAvatarStream + useAudioHandler + transcript accumulation + start/stop logic. The HCP editor needs the exact same functionality. Interface:

interface PlaygroundPreviewPanelProps {
  hcpProfileId?: string;
  vlInstanceId?: string;
  systemPrompt?: string;
  avatarCharacter?: string;
  avatarStyle?: string;
  avatarEnabled: boolean;
  disabled?: boolean;  // true for new profiles (no id yet)
}

• Duplicating Playground code: Do NOT copy-paste the test session logic from vl-instance-editor.tsx. Extract into a shared component.
• Inlining useQuery in components: Follow project convention -- all queries go through hooks in hooks/ directory. [VERIFIED: CLAUDE.md rule]
• Static route ordering violation: Any new endpoint added to hcp_profiles.py must come BEFORE /{profile_id} routes. Add preview-instructions route after batch-sync but before /{profile_id}. [VERIFIED: CLAUDE.md Gotcha #3]

Key insight: This phase is primarily a UI restructuring and composition phase. Nearly every functional building block already exists in the codebase. The risk is in duplicating rather than reusing existing components.

What goes wrong: The CONTEXT.md explicitly calls out that to_prompt_dict() needs to include agent_instructions_override. Currently it does NOT (verified in hcp_profile.py lines 84-100). Why it happens: to_prompt_dict() was originally designed for system prompt construction and predates the override field. How to avoid: Add agent_instructions_override to the return dict in to_prompt_dict(). The build_agent_instructions function already checks for it (line 62-63 of agent_sync_service.py). Warning signs: Instructions preview always returns template-generated text, never the override.

What goes wrong: New route /{profile_id}/preview-instructions added after /{profile_id} gets shadowed by the /{profile_id} route. Why it happens: FastAPI matches the first route that fits the pattern. How to avoid: Place the new endpoint after batch-sync (line 161) but before /{profile_id} (line 120). Better yet, use a path like POST /{profile_id}/preview-instructions which won't conflict because it uses POST and has a sub-path. Warning signs: 404 or wrong handler executing.

What goes wrong: Switching between Profile and Voice & Avatar tabs loses form state. Why it happens: If Form wrapper doesn't encompass both tabs. How to avoid: The current architecture already wraps <Form {...form}> around <Tabs> (line 276 of hcp-profile-editor.tsx). This pattern MUST be preserved. [VERIFIED: codebase decision from Phase 12] Warning signs: Data entered in one tab disappears when switching.

What goes wrong: Clicking Start on a new (unsaved) profile attempts WebSocket connection with no profile ID. Why it happens: New profiles have isNew=true and no database ID. How to avoid: Disable the Start button when isNew is true. Show helper text: "Save profile first to test." Warning signs: WebSocket errors or empty sessions.

What goes wrong: Building full file upload / function call UI instead of placeholder skeleton. Why it happens: The CONTEXT.md's decision section mentions Knowledge & Tools inline config, but the Deferred section explicitly marks full functionality as out of scope. How to avoid: Build collapsible sections with descriptive placeholder content only. No actual upload/API integration. Warning signs: Sprint overrun, blocked on unbuilt backend features.

What goes wrong: TypeScript compilation fails due to unused imports (BookOpen, Wrench) after removing Knowledge/Tools tabs. Why it happens: Tab placeholder components imported icons that are no longer needed. How to avoid: Clean up imports when removing tab content. npx tsc -b will catch these. [VERIFIED: CLAUDE.md pre-commit checklist] Warning signs: Build failures in CI.

# Source: pattern derived from agent_sync_service.build_agent_instructions [VERIFIED: codebase]
# Place AFTER /batch-sync but BEFORE /{profile_id} routes

class InstructionsPreviewRequest(BaseModel):
    """Profile data for instructions generation preview."""
    name: str = ""
    specialty: str = ""
    hospital: str = ""
    title: str = ""
    personality_type: str = "friendly"
    emotional_state: int = 50
    communication_style: int = 50
    expertise_areas: list[str] = []
    prescribing_habits: str = ""
    concerns: str = ""
    objections: list[str] = []
    probe_topics: list[str] = []
    difficulty: str = "medium"
    agent_instructions_override: str = ""

class InstructionsPreviewResponse(BaseModel):
    """Generated instructions text."""
    instructions: str
    is_override: bool

@router.post("/preview-instructions", response_model=InstructionsPreviewResponse)
async def preview_instructions(
    body: InstructionsPreviewRequest,
    user: User = Depends(require_role("admin")),
):
    """Preview auto-generated agent instructions from profile data. Admin only."""
    from app.services.agent_sync_service import build_agent_instructions
    profile_data = body.model_dump()
    instructions = build_agent_instructions(profile_data)
    is_override = bool(body.agent_instructions_override and body.agent_instructions_override.strip())
    return InstructionsPreviewResponse(instructions=instructions, is_override=is_override)

// Source: composition pattern from vl-instance-editor.tsx [VERIFIED: codebase]
export function VoiceAvatarTab({ form, profile, isNew }: VoiceAvatarTabProps) {
  return (
    <div className="grid grid-cols-1 lg:grid-cols-2 gap-6">
      {/* Left Panel: Configuration */}
      <div className="space-y-4">
        <AgentConfigLeftPanel form={form} profile={profile} isNew={isNew} />
      </div>
      {/* Right Panel: Playground Preview */}
      <div>
        <PlaygroundPreviewPanel
          hcpProfileId={profile?.id}
          vlInstanceId={form.watch("voice_live_instance_id") ?? undefined}
          systemPrompt={form.watch("agent_instructions_override") ?? ""}
          avatarCharacter={form.watch("avatar_character")}
          avatarStyle={form.watch("avatar_style")}
          avatarEnabled={!!form.watch("avatar_character")}
          disabled={isNew}
        />
      </div>
    </div>
  );
}

// Source: pattern derived from existing form fields + new preview hook [VERIFIED: codebase]
import { Wand2 } from "lucide-react";

function InstructionsSection({ form, profileId }: { form: UseFormReturn<HcpFormValues>; profileId?: string }) {
  const { t } = useTranslation("admin");
  const [autoInstructions, setAutoInstructions] = useState("");
  const [isGenerating, setIsGenerating] = useState(false);

  const handleGenerate = async () => {
    setIsGenerating(true);
    try {
      const formValues = form.getValues();
      const result = await previewInstructions(formValues);
      setAutoInstructions(result.instructions);
    } finally {
      setIsGenerating(false);
    }
  };

  return (
    <Card>
      <CardHeader>
        <div className="flex items-center justify-between">
          <CardTitle className="text-sm">{t("admin:hcp.autoInstructions")}</CardTitle>
          <Button variant="ghost" size="sm" onClick={handleGenerate} disabled={isGenerating}>
            <Wand2 className="size-4 mr-1" />
            {isGenerating ? "..." : t("common:generate")}
          </Button>
        </div>
      </CardHeader>
      <CardContent className="space-y-3">
        {autoInstructions && (
          <pre className="text-xs bg-muted/50 rounded p-3 max-h-48 overflow-y-auto whitespace-pre-wrap">
            {autoInstructions}
          </pre>
        )}
        <FormField
          control={form.control}
          name="agent_instructions_override"
          render={({ field }) => (
            <FormItem>
              <FormLabel>{t("admin:hcp.overrideInstructions")}</FormLabel>
              <FormControl>
                <Textarea rows={4} placeholder={t("admin:hcp.overridePlaceholder")} {...field} />
              </FormControl>
            </FormItem>
          )}
        />
      </CardContent>
    </Card>
  );
}

Deprecated/outdated:

• Knowledge tab placeholder (added Phase 14-03, removed Phase 15)
• Tools tab placeholder (added Phase 14-03, removed Phase 15)

1. Instructions generation timing

   • What we know: The magic wand button calls backend on-demand (CONTEXT.md: Claude's Discretion area)
   • What's unclear: Should auto-generated instructions load automatically when tab opens (initial load), or only when user clicks the wand?
   • Recommendation: Load on tab mount for existing profiles (cheap GET call), require explicit click for new profiles. This provides immediate feedback while keeping UX responsive.

2. Playground test scope

   • What we know: CONTEXT.md says "Start test button (reuse VL Instance Editor test logic)" and Deferred says "full real-time conversation first phase = UI structure + Start button"
   • What's unclear: Should the Start button actually connect to Voice Live (full test), or just show UI skeleton?
   • Recommendation: Implement full Start/Stop functionality by extracting from vl-instance-editor.tsx. The hooks already exist and the code is proven. Only defer if Azure credentials are not configured (show appropriate message).

3. Playground preview for new profiles

   • What we know: New profiles have no ID, can't test
   • What's unclear: Should we show a static avatar preview image even without a live connection?
   • Recommendation: Show static avatar thumbnail based on selected avatar_character + avatar_style from form state, with disabled Start button and helper text.

Step 2.6: SKIPPED (no external dependencies identified -- this phase is code/config changes only using existing project dependencies).

• Codebase analysis of all files listed in CONTEXT.md canonical_refs -- verified current state of every component
• hcp-profile-editor.tsx (572 lines) -- current 4-tab structure, Form wrapping Tabs
• voice-avatar-tab.tsx (307 lines) -- current read-only VL preview, will be rewritten
• vl-instance-editor.tsx (~700+ lines) -- Playground test pattern to extract
• agent_sync_service.py (565 lines) -- build_agent_instructions function
• hcp_profile.py (100 lines) -- to_prompt_dict() missing override field
• hcp_profiles.py API router -- route ordering, existing endpoints

• Project STATE.md accumulated decisions -- confirmed Form-wraps-Tabs pattern (Phase 12), VoiceAvatarTab rewrite (Phase 14)

Confidence breakdown:

• Standard stack: HIGH - all components already exist in codebase, no new dependencies
• Architecture: HIGH - pattern directly extracted from existing vl-instance-editor.tsx
• Pitfalls: HIGH - identified from concrete codebase analysis (route ordering, form state, missing field)

Research date: 2026-04-07 Valid until: 2026-05-07 (stable -- internal refactoring phase, no external API changes)

Visual and interaction contract for the HCP Editor Agent Config Center phase. Generated by gsd-ui-researcher, verified by gsd-ui-checker.

Source: Pre-populated from codebase analysis (frontend/src/styles/index.css, frontend/src/components/ui/). Project has been using this stack since Phase 01.

Declared values (must be multiples of 4):

Exceptions:

• Playground preview panel avatar/orb container uses 240px min-height (fixed to match VL Instance Editor pattern in vl-instance-editor.tsx)
• Touch target for Start/Stop test button: 44px height minimum (accessibility)

Source: Pre-populated from frontend/src/styles/index.css base layer rules (lines 252-297). Matches project-wide typography contract established in Phase 01.

Accent reserved for:

1. "Save" button (primary CTA)
2. "Start" test button in Playground panel
3. Voice Mode toggle switch when enabled (on state)
4. Magic wand (regenerate instructions) button icon on hover
5. Active tab indicator underline
6. VL Instance link badge when connected

+------------------------------------------------------------------+
| [Profile Tab]  [Voice & Avatar Tab (active)]                     |
+------------------------------------------------------------------+
| LEFT PANEL (config)          | RIGHT PANEL (playground)          |
| 50% width on lg+             | 50% width on lg+                 |
| 100% width on mobile         | 100% width on mobile (stacks)    |
|                              |                                   |
| +-- Model Deployment ------+ | +-- Playground ----------------+ |
| | [tiered model dropdown]  | | |                               | |
| +--------------------------+ | |  [AvatarView or AudioOrb]     | |
|                              | |   240px min-height             | |
| +-- Voice Mode ------------+ | |                               | |
| | [toggle switch]           | | |  [Start / Stop button]       | |
| | [VL Instance selector]   | | |                               | |
| | (visible when enabled)    | | |  +-- Transcript -----------+ | |
| +--------------------------+ | |  | [scrollable chat log]    | | |
|                              | |  | 200px max-height         | | |
| +-- Instructions ----------+ | |  +--------------------------+ | |
| | [auto-gen preview (ro)]  | | +-------------------------------+ |
| | [magic wand button]      | |                                   |
| | [override textarea]      | |                                   |
| +--------------------------+ |                                   |
|                              |                                   |
| +-- Knowledge & Tools -----+ |                                   |
| | [collapsible section]     | |                                   |
| | [placeholder content]     | |                                   |
| +--------------------------+ |                                   |
+------------------------------------------------------------------+

CSS Grid: grid grid-cols-1 lg:grid-cols-2 gap-6 Left panel: space-y-4 for vertical section stacking Right panel: sticky top-4 for scroll-following on large screens

Removed tabs: knowledge, tools (were placeholders from Phase 14-03)

[New Profile]
  -> Playground: Start disabled, helper text shown
  -> Instructions: Wand click only (no auto-load)
  -> Voice Mode: Toggle available but no persistence until save

[Saved Profile, No VL Instance]
  -> Playground: Start disabled, "Assign VL Instance to test"
  -> Instructions: Auto-load on tab mount
  -> Voice Mode: OFF

[Saved Profile, VL Instance Assigned]
  -> Playground: Start enabled
  -> Instructions: Auto-load on tab mount
  -> Voice Mode: ON with instance shown

[Playground Test Active]
  -> Start button -> Stop button
  -> VoiceControls visible (mute)
  -> Transcript accumulates in real-time
  -> Avatar/Orb shows speaking/listening state
  -> Other form fields remain editable

[Playground Test Stopped]
  -> Stop button -> Start button
  -> Transcript preserved (not cleared until next Start)
  -> VoiceControls hidden

Total new i18n keys: 17 (both en-US and zh-CN) Existing reused i18n keys: 6

Tab bar: Full-width TabsList with 2 tabs (Profile, Voice & Avatar), each flex-1.

This phase uses only existing Radix UI wrapper components from frontend/src/components/ui/. No new component library installations or registry imports required.

• Dimension 1 Copywriting: PASS
• Dimension 2 Visuals: PASS
• Dimension 3 Color: PASS
• Dimension 4 Typography: PASS
• Dimension 5 Spacing: PASS
• Dimension 6 Registry Safety: PASS

Approval: pending

Phase Goal: Refactor HCP editor to Agent Config Center aligned with Azure AI Foundry Agent editing experience. Remove empty Knowledge/Tools tabs, upgrade Voice & Avatar tab to full Agent config layout: Model Deployment selector, Voice Mode toggle + VL Instance binding, auto-generated + editable override Instructions, right-side Playground preview panel (digital human/audio orb + Start test).

Verified: 2026-04-07T10:15:00Z Status: human_needed Re-verification: No -- initial verification

Score: 5/5 truths verified

Test: Open HCP editor, click Voice & Avatar tab, verify the two-panel responsive grid layout Expected: Left panel shows Model Deployment, Voice Mode toggle, VL Instance selector, Instructions section, Knowledge & Tools. Right panel shows Playground with avatar/orb area, Start button, transcript. Why human: Visual layout, responsive behavior, and UX alignment with Azure AI Foundry style cannot be verified programmatically

Test: Click magic wand button in Instructions section on an existing HCP profile Expected: Auto-generated instructions appear in preview area containing profile name and specialty Why human: End-to-end flow through backend endpoint requires running server and human observation

Test: Toggle Voice Mode switch ON/OFF Expected: VL Instance selector appears/disappears, form value cleared on toggle off Why human: Interactive toggle behavior requires visual confirmation

Test: Enter data on Profile tab, switch to Voice & Avatar, switch back Expected: Form data persists across tab switches Why human: State persistence across UI interactions needs human observation

Test: Switch language to zh-CN and navigate to HCP editor Voice & Avatar tab Expected: All new labels display in Chinese (model deployment, voice mode, playground, etc.) Why human: Translation quality and completeness requires visual inspection

Test: Navigate directly to HCP editor URL with ?tab=knowledge or ?tab=tools Expected: Falls back to Profile tab without console errors Why human: URL-based navigation testing requires browser interaction

No code-level gaps found. All 5 observable truths verified with full artifact existence, substantive implementation, wiring, and data-flow confirmation. All 5 phase requirements (HCP-15-01 through HCP-15-05) satisfied.

6 items require human visual verification before the phase can be marked as fully passed -- all relate to interactive UI behavior and visual layout that cannot be assessed through static code analysis or programmatic checks.

Verified: 2026-04-07T10:15:00Z Verifier: Claude (gsd-verifier)