# AGENTS.md - Cognitive Clarity Workspace Instructions

Welcome to **Cognitive Clarity** (`clarity-helper`), an adaptive clinical training and roleplay environment engineered to strengthen cognitive flexibility, practice Cognitive Behavioral Therapy (CBT) restructuring techniques, and simulate high-stakes social interactions in real time.

---

## 1. System Architecture Overview

```mermaid
graph TD
    User([User Voice / Text]) <--> Frontend[React 19 + Vite + Tailwind + Radix UI]
    
    subgraph "Frontend Real-Time Multimodal Layer"
        Frontend <--> WebAudio[WebAudio DSP Engine: Live FFT Analysis & Synthesis]
        Frontend <--> OpenRouterClient[OpenRouter API: Streaming Roleplay & TTS/STT]
        OpenRouterClient --> Transcripts[Real-Time Transcription Pipeline]
        Transcripts --> Supervisor[Parallel Turn Supervisor: OpenRouter google/gemini-3.8-flash]
        Supervisor --> LiveInsights[LiveInsightPanel & SessionReport]
    end

    subgraph "Backend Serverless Layer (api/)"
        Frontend -.->|Optional Enterprise Fallback| AzFunc[Azure Functions v4 .NET 8 Isolated Worker]
        AzFunc --> ChatFunc["/api/chat (ChatProgression)"]
        AzFunc --> AnalysisFunc["/api/analysis (ClinicalAnalysis)"]
        AzFunc --> ScenarioFunc["/api/scenario/generate (GenerateScenario)"]
        AzFunc <--> OpenRouterAPI[OpenRouter API Endpoint /chat/completions]
    end

    subgraph "Local Persistence & Offline"
        Frontend <--> LocalStorage[LocalStorage: Custom Scenarios, Settings & Session History]
        Frontend <--> ServiceWorker[Vite PWA / Workbox Service Worker: sw.ts]
    end
```

---

## 2. Core Repository Structure

```
clarity-helper/
├── App.tsx                     # Primary application router, state coordinator, and hero interface
├── constants.ts                # CBT Glossary (12 distortions, 5 techniques, 2 concepts), default scenarios, schemas
├── types.ts                    # TypeScript domain models (Scenario, AnalysisResult, UserSettings, Message)
├── index.html / index.tsx      # HTML entry point & React root mount
├── index.css                   # Global styles & Tailwind base directives
├── vite.config.ts              # Vite 6 config with PWA injectManifest, aliases, and env injection
├── sw.ts                       # Custom Workbox Service Worker with precaching and caching strategies
├── api/                        # Azure Functions .NET 8 Isolated Worker backend
│   ├── Program.cs              # Functions host bootstrap & Application Insights telemetry
│   ├── api.csproj              # .NET 8 project file with HttpClient Factory
│   ├── ChatFunction.cs         # POST /api/chat - Headless roleplay progression via OpenRouter
│   ├── AnalysisFunction.cs     # POST /api/analysis - Real-time clinical evaluation via OpenRouter
│   └── ScenarioFunction.cs     # POST /api/scenario/generate - Structured scenario generator via OpenRouter
├── components/                 # UI Component Hierarchy
│   ├── VoiceSession.tsx        # Multimodal voice roleplay controller
│   ├── VoiceSession/           # Voice state components (Header, Controls, Visualizer states)
│   ├── ChatSession.tsx         # Text-based roleplay controller with streaming SSE
│   ├── ChatMessage.tsx         # Conversation bubble with role styling
│   ├── ChatInput.tsx           # Text input with submit handling
│   ├── LiveInsightPanel.tsx    # Real-time turn-by-turn clinical supervision drawer
│   ├── SessionReport.tsx       # Comprehensive post-session CBT assessment report
│   ├── ScenarioGenerator.tsx   # AI-powered interactive custom scenario builder
│   ├── CBTReference.tsx        # Interactive searchable glossary & technique reference
│   ├── AudioVisualizer.tsx     # Canvas/CSS real-time FFT frequency visualizer
│   ├── AudioDeviceSelector.tsx # Input microphone selector modal
│   ├── SettingsModal.tsx       # Voice profile & OpenRouter API key configuration
│   ├── ReloadPrompt.tsx        # PWA update notification prompt
│   └── ui/                     # Radix UI + Tailwind design system primitives
├── hooks/
│   └── useLiveSession.ts       # Low-level WebAudio + OpenRouter voice synthesis hook
├── services/
│   ├── apiConfig.ts            # OpenRouter API key resolution & model defaults
│   ├── openRouterService.ts    # Streaming chat, structured supervision & speech API client
│   ├── sessionStorage.ts       # Persistent session history, markdown and JSON report exports
│   └── audioUtils.ts           # PCM16 / Base64 / AudioBuffer encoding and decoding helpers
├── scripts/                    # Headless CLI tools and scenario test suites
│   ├── validate-scenarios.ts   # Scenario schema and distortion coverage validator
│   └── simulate-cbt-session.ts # Headless multi-turn roleplay & clinical scoring simulator
├── test/                       # Automated Node.js / tsx unit test suite
│   ├── apiConfig.test.ts       # API key resolution & model defaults tests
│   ├── openRouterService.test.ts # Streaming, supervisor & scenario generation tests
│   └── scenarios.test.ts       # Clinical scenario schema & glossary tests
└── .agents/                    # Specialized agent skills and workflow blueprints
    └── skills/                 # Domain-specific skill runbooks
```

---

## 3. Engineering Invariants & Coding Guidelines

### 3.1 Strict Clinical Roleplay Separation
- **No Meta-Commentary Leaks**: When the AI character is engaged in roleplay (`ChatSession`, `VoiceSession`, `ChatFunction.cs`), system instructions MUST forbid the model from breaking character, congratulating the user, giving clinical advice, or outputting feedback tokens.
- **Parallel Supervision**: Clinical feedback is exclusively computed out-of-band by a dedicated supervisor model instance (`LiveInsightPanel`, `AnalysisFunction.cs`), ensuring realistic emotional friction during the simulation.

### 3.2 OpenRouter Exclusive API Policy
- **Zero Direct Google API Keys**: The codebase must NOT require or use direct Google Gemini API keys. All model queries (`google/gemini-3.8-flash`, `google/gemini-3.7-flash`, `google/gemini-2.5-flash`, `anthropic/claude-3.5-haiku`, `meta-llama/llama-3.3-70b-instruct`) route exclusively through OpenRouter.
- **Client Security**: OpenRouter API Keys provided by the user are stored in browser LocalStorage and never sent to external servers or telemetries.

### 3.3 TypeScript & Build Hygiene
- Keep `npm run lint` (`tsc --noEmit`) and `npm test` passing with zero errors.
- Ensure all Radix UI component props utilize `React.ComponentPropsWithoutRef<T>` or type unions compatible with React 19.
- Maintain full type synchronization between `types.ts` and backend C# DTOs in `api/*.cs`.

### 3.4 .NET Azure Functions Backend
- Target **.NET 8.0** isolated worker model with `Microsoft.Azure.Functions.Worker.Sdk`.
- Call OpenRouter API via `HttpClientFactory` with `OPENROUTER_API_KEY`.

---

## 4. Verification & Testing Commands

| Purpose | Command | Notes |
|:---|:---|:---|
| **Run Unit Tests** | `npm test` | Executes native Node.js / `tsx` unit test suites |
| **Typecheck Frontend** | `npm run lint` | Runs `tsc --noEmit` |
| **Build Frontend** | `npm run build:nobump` | Bundles Vite SPA + PWA Service Worker to `dist/` |
| **Validate Scenarios** | `npm run validate:scenarios` | Validates default & custom scenario data schemas |
| **Simulate Session** | `npm run simulate:session` | Executes headless 3-turn CBT simulation with clinical score |
| **Build .NET API** | `dotnet build api/api.csproj` | Compiles Azure Functions Isolated Worker assembly |
| **Run Dev Server** | `npm run dev` | Starts Vite on `http://localhost:3000` |