diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 0b9fba64..ed10c9ed 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -21,7 +21,7 @@ jobs:
strategy:
fail-fast: false
matrix:
- os: [ubuntu-latest, windows-latest]
+ os: [ubuntu-latest, windows-latest, macos-latest]
include:
- os: ubuntu-latest
script: linux
@@ -32,6 +32,11 @@ jobs:
script: win
artifact_glob: |
dist/*.exe
+ - os: macos-latest
+ script: mac
+ artifact_glob: |
+ dist/*.dmg
+ dist/*-mac.zip
steps:
- name: Checkout
@@ -83,7 +88,11 @@ jobs:
shell: pwsh
run: git config --system core.longpaths true
- - name: Build
+ # Building x64 and arm64 DMGs in one electron-builder invocation races
+ # hdiutil on GitHub's Apple Silicon runners. Run each architecture in a
+ # separate invocation so each disk image is detached before the next.
+ - name: Build macOS architectures sequentially
+ if: matrix.os == 'macos-latest'
shell: bash
env:
# Intentionally do NOT set CSC_LINK / WIN_CSC_LINK etc.
@@ -93,6 +102,15 @@ jobs:
# opt-in: add the secrets to the repo and wire them in here
# only when you have real certificates.
CSC_IDENTITY_AUTO_DISCOVERY: 'false'
+ run: |
+ npx electron-builder --mac dmg zip --x64 --publish never
+ npx electron-builder --mac dmg zip --arm64 --publish never
+
+ - name: Build
+ if: matrix.os != 'macos-latest'
+ shell: bash
+ env:
+ CSC_IDENTITY_AUTO_DISCOVERY: 'false'
run: npm run build:${{ matrix.script }} -- --publish never
- name: Upload artifacts
@@ -179,15 +197,13 @@ jobs:
| Platform | File | Notes |
|---|---|---|
- | **Windows** | `OpenCluely-Setup-*.exe` | NSIS installer — installs app + adds to Start Menu |
- | **Linux** | `*.deb` | Debian/Ubuntu — auto-pulls system deps (Python, ffmpeg, GTK) |
- | **Linux** | `*.AppImage` | Universal — no install, just `chmod +x` and run |
+ | **macOS (Intel)** | `OpenCluely-*.dmg` or `*-mac.zip` | Unsigned build; use Finder's **Open** confirmation on first launch. |
+ | **macOS (Apple Silicon)** | `OpenCluely-*-arm64.dmg` or `*-arm64-mac.zip` | Unsigned build; use Finder's **Open** confirmation on first launch. |
+ | **Windows** | `OpenCluely-Setup-*.exe` | NSIS installer — installs app + adds to Start Menu. |
+ | **Linux** | `*.deb` | Debian/Ubuntu package. |
+ | **Linux** | `*.AppImage` | Universal package — run `chmod +x` then launch. |
- > **macOS:** no pre-built build is shipped. The app is unsigned/un-notarized, so macOS Gatekeeper blocks it as "damaged". Run OpenCluely from source instead:
- > ```bash
- > git clone https://github.com/TechyCSR/OpenCluely && cd OpenCluely && ./setup.sh
- > ```
- > Requires Node.js 18+. See the [README](https://github.com/TechyCSR/OpenCluely#quick-start) for details.
+ This beta is for authorised interview preparation and professional development. Do not use it where external assistance is not permitted.
## First Run
@@ -236,6 +252,10 @@ jobs:
# The order below is the order files appear in the release page.
find artifacts -type f -name 'OpenCluely-Setup-*.exe' \
-exec cp -v {} release/ \;
+ find artifacts -type f -name 'OpenCluely-*.dmg' \
+ -exec cp -v {} release/ \;
+ find artifacts -type f -name 'OpenCluely-*-mac.zip' \
+ -exec cp -v {} release/ \;
find artifacts -type f -name 'opencluely_*_amd64.deb' \
-exec cp -v {} release/ \;
find artifacts -type f -name '*.AppImage' \
@@ -255,7 +275,7 @@ jobs:
tag_name: ${{ github.ref_name }}
name: OpenCluely ${{ github.ref_name }}
draft: false
- prerelease: false
+ prerelease: ${{ contains(github.ref_name, '-') }}
body_path: RELEASE_BODY.md
files: |
release/*
diff --git a/.gitignore b/.gitignore
index 57cbcfa0..0af412b2 100644
--- a/.gitignore
+++ b/.gitignore
@@ -7,3 +7,4 @@ dist/
bin/
.DS_Store
*.log
+knowledge/*.local.md
diff --git a/README.md b/README.md
index a2ed045f..95e76069 100644
--- a/README.md
+++ b/README.md
@@ -2,19 +2,19 @@
# OpenCluely
-**The invisible AI interview copilot.**
+**A local-first AI interview-practice workspace.**
-Real-time AI help on a stealth overlay that screen sharing cannot see. Ask by voice or screenshot, and get clear answers that stream in as you need them.
+Practice technical, behavioral, and role-specific interviews with voice, chat, screenshots, and concise streamed answers.
- 
- 
+ 
+ 
-Website |
-Download |
+Repository |
+Builds |
Quick start |
How it works
@@ -26,37 +26,43 @@ https://github.com/user-attachments/assets/896a7140-1e85-405d-bfbe-e05c9f3a816b
## What it is
-OpenCluely is a desktop app for technical interviews and practice. It places a small overlay on your screen that recording and conferencing tools do not capture. You can speak a question or take a screenshot, and the AI answers in real time. The answer streams into a floating window and an optional chat panel, with clean code blocks and syntax highlighting.
+OpenCluely V3 beta is a local-first Universal Career Copilot for authorised interview practice and professional development. Choose a role pack, add your verified career and target-job context, then practise with chat, voice, screenshots, concise answers, and follow-up questions. Answers stream into a floating workspace and optional chat panel, with clean code blocks and syntax highlighting.
-It is free and open source. Processing stays on your machine, and the only thing that leaves your device is the request you send to the AI provider.
+It is free and open source. Application state and diagnostics remain local; Gemini and Azure receive only the requests required for the features you enable. Use it for preparation and only where external assistance is permitted.
+
+### Current release: [v3.0.0-beta.3](https://github.com/RahulSinghParmar/OpenCluely/releases/tag/v3.0.0-beta.3)
+
+V3 beta unifies the role catalogue, candidate/job context, response modes, technology focus, streaming performance diagnostics, Azure/Whisper voice input, and local settings persistence. Voice responses now render incrementally in both Chat and the floating response window.
## Highlights
-- **Invisible overlay.** Windows stay out of Zoom, Google Meet, Microsoft Teams, Discord, and OBS captures. You see the answer, the call does not.
-- **Hidden during screen share.** When a share starts, the app can hide every window on its own.
-- **Flexible local voice.** Choose manual start/stop capture or automatic voice-activity detection without fixed-timer sentence cuts.
-- **Configurable streamed answers.** Route voice replies to chat, the floating overlay, or both.
+- **Career workspace.** Keep a locally stored candidate profile and target-job context for truthful HR, role-fit, and behavioral practice.
+- **Responsive voice practice.** Azure Speech and local Whisper support microphone transcription; final transcripts render immediately and Gemini responses stream into Chat and the floating response window.
+- **Configurable answer routing.** Send voice replies to Chat, the floating response window, or both.
- **Direct image analysis.** Screenshots go straight to Gemini for visual reasoning, with no slow OCR step in between.
- **Session memory.** The whole conversation is remembered, so follow-ups, edge cases, and optimizations keep their context.
-- **Language aware.** Tailored answers for C++, C, Python, Java, and JavaScript.
-- **Stealthy by design.** Runs under ordinary system names, ships with no telemetry, and keeps your session local.
-- **Cross platform.** Pre-built installers for Windows and Linux (.deb and AppImage). macOS runs from source in one command.
+- **Interview profiles.**, DevOps, SDET, Backend Engineer, STAR, Leadership Principles, and 30+ additional skill profiles.
+- **Response modes.** Quick, interview-ready, detailed, STAR, and troubleshooting formats.
+- **Language aware.** Python, Java, JavaScript, TypeScript, Go, Rust, C, C++, C#, Kotlin, Swift, PHP, Ruby, Bash, and PowerShell.
+- **Local diagnostics.** View latency metrics, open logs, or copy redacted diagnostics from Settings.
+- **Cross platform packages.** macOS DMG/ZIP, Windows NSIS installer, and Linux Debian/AppImage artifacts are produced from the same Electron Builder configuration.
-## Download
+## Builds
-Pre-built installers are published with every release. These links always point at the newest version.
+Download the V3 beta assets from the [v3.0.0-beta.3 release](https://github.com/RahulSinghParmar/OpenCluely/releases/tag/v3.0.0-beta.3). If an artifact is unavailable for a platform, run the source build with `npm start` instead.
| Platform | File | Notes |
|---|---|---|
-| Windows | [Setup .exe](https://github.com/TechyCSR/OpenCluely/releases/latest) | NSIS installer. Adds a Start Menu shortcut. |
-| Linux (Debian or Ubuntu) | [.deb](https://github.com/TechyCSR/OpenCluely/releases/latest) | Pulls system deps automatically (Python, ffmpeg, GTK). |
-| Linux (universal) | [.AppImage](https://github.com/TechyCSR/OpenCluely/releases/latest) | No install. Run `chmod +x` then launch. |
+| Windows | [Setup .exe](https://github.com/RahulSinghParmar/OpenCluely/releases/tag/v3.0.0-beta.3) | NSIS installer when published from a Windows-capable build host. |
+| Linux (Debian or Ubuntu) | [.deb](https://github.com/RahulSinghParmar/OpenCluely/releases/tag/v3.0.0-beta.3) | Debian package when published from a Linux-capable build host. |
+| Linux (universal) | [.AppImage](https://github.com/RahulSinghParmar/OpenCluely/releases/tag/v3.0.0-beta.3) | Portable Linux package when published from a Linux-capable build host. |
+| macOS | [.dmg / .zip](https://github.com/RahulSinghParmar/OpenCluely/releases/tag/v3.0.0-beta.3) | Intel (`x64`) and Apple Silicon (`arm64`) packages. |
-> **macOS:** there is no pre-built download. The app is unsigned and un-notarized, so macOS Gatekeeper blocks it as "damaged and can't be opened." Run OpenCluely from source instead — see [Quick start](#quick-start). It is a one-line `./setup.sh` once Node.js is installed.
+> **macOS:** builds are currently unsigned and un-notarized. Run from source for the most reliable experience. When DMG/ZIP assets are attached to the release, macOS may require Finder’s **Open** confirmation on first launch.
-Every build is produced automatically on GitHub Actions and ships with SHA-256 checksums. Each release also lists the full set of commits it includes.
+Each GitHub tag includes automatic source ZIP and TAR archives. Release assets are attached separately after local validation.
-The website at [opencluely.techycsr.dev](https://opencluely.techycsr.dev) detects your operating system and offers the right installer directly.
+Project updates and releases are published at [RahulSinghParmar/OpenCluely](https://github.com/RahulSinghParmar/OpenCluely).
## Quick start
@@ -65,7 +71,7 @@ If you would rather build from source, three steps are all it takes.
1. Clone the repository.
```bash
- git clone https://github.com/TechyCSR/OpenCluely.git
+ git clone https://github.com/RahulSinghParmar/OpenCluely.git
cd OpenCluely
```
@@ -157,30 +163,43 @@ For Azure Speech, create a Speech resource in the [Azure Portal](https://portal.
OpenCluely is under active development. The core is stable and improvements ship regularly.
+## Universal skill system
+
+Skills are now defined through a central catalog instead of a DSA-only model. Every skill supplies a system prompt, knowledge scope, response style, display format, latency preferences, and language preferences. Static Markdown prompts remain supported as overrides for specialized skills.
+
+- **Interview:** , SDET, QA Automation, DevOps, Backend, Frontend, Full Stack, Cloud, Security, Network, System Administrator, Linux, Database, Data, AI, ML, SRE, Platform.
+- **General:** HR Interview, Behavioral Interview, STAR, Leadership Principles, Resume Review, Salary Negotiation, Career Coaching.
+- **Education:** DSA, Operating Systems, Networking, Databases, System Design, OOP, Software Architecture.
+- **General AI:** Explain Concepts, Research Assistant, Meeting Assistant, Technical Documentation, Coding Assistant.
+
### Done
-- Stealth overlay with a draggable command bar and a click through toggle
-- Hidden during screen share, with automatic hiding when a share begins
+- Draggable command bar and click-through toggle for a focused local workspace
- Screenshot capture with direct Gemini analysis, no OCR step
- Configurable manual or VAD-driven voice capture
- Persistent local Whisper worker with optional CUDA acceleration and idle GPU release
- Configurable chat/overlay routing for streamed voice answers
+- Incremental Gemini rendering in both Chat and the floating response window
- Whisper hallucination filter that drops phantom phrases on silence
- AI response window with markdown and syntax highlighting
- Global shortcuts for capture, visibility, interaction, chat, and settings
- Session memory and a full chat UI
-- Language picker and a DSA skill prompt
+- Universal skill catalogue with, DevOps, SDET, Backend, STAR, Leadership Principles, HR, education, and general AI profiles
+- Company focus, response modes, theme, compact mode, and expanded programming-language settings
+- Performance metrics and redacted diagnostic-log export
+- macOS panel-based overlay and chat behavior across Spaces and full-screen applications
- Optional Azure Speech and local Whisper, with an auto hiding mic button
+- Persisted active role, language, company focus, response mode, appearance, candidate profile, and target job profile
- Multi-monitor and area capture support
- Window binding and positioning
-- Settings management with disguise and stealth modes
+- Persistent local settings and role-pack selection
### Planned
- Multiple model backends alongside Gemini (OpenAI, Anthropic, local)
- Auto typing of code snippets into editors and IDEs
- Export of conversation history to markdown or PDF
-- Deeper stealth, including process name randomization
+- Optional local candidate-profile and document knowledge management (not shipped yet)
## Troubleshooting
@@ -207,7 +226,7 @@ OpenCluely is under active development. The core is stable and improvements ship
Limitations
-- **Screen-capture invisibility does not work on Linux.** The overlay stays hidden from screen shares and recordings only on **macOS** and **Windows**. This relies on Electron's `setContentProtection`, which maps to `NSWindowSharingNone` on macOS and `WDA_EXCLUDEFROMCAPTURE` on Windows. Electron provides **no equivalent on Linux** (neither X11 nor Wayland), so on Linux the call is a silent no-op and the overlay **will be visible** to anyone you screen-share with. This is a platform limitation, not a bug — there is no window flag on Linux that excludes a window from framebuffer capture. If you need capture-invisibility, run OpenCluely on macOS or Windows. As a partial workaround on Linux, share a single application window instead of your entire screen, or place the overlay on a monitor you are not sharing.
+- **Visibility is not guaranteed.** Do not rely on any desktop overlay to be absent from screen shares, recordings, remote-management tools, proctoring, or employer monitoring. Close the application during an interview unless the employer explicitly permits its use.
@@ -232,6 +251,116 @@ Released under the MIT License. See [LICENSE](LICENSE) for details.
-Built by [TechyCSR](https://techycsr.dev). If OpenCluely helped you, consider giving it a star ⭐
+Maintained by [RahulSinghParmar](https://github.com/RahulSinghParmar). If OpenCluely helped you, consider giving it a star ⭐
+
+## Architecture review and delivery plan
+
+OpenCluely is an Electron desktop application for authorized interview practice and preparation. It provides profile-aware chat, voice, and screen-question flows. Use it only where external assistance is permitted.
+
+### Current architecture
+
+```mermaid
+flowchart LR
+ UI["Renderer windows\nOverlay · Chat · Settings · Response"] --> P["preload.js\nallowlisted IPC"]
+ P --> M["ApplicationController\nmain.js"]
+ M --> W[WindowManager]
+ M --> S[SessionManager]
+ M --> SP["SpeechService\nAzure / Whisper"] --> A[Azure Speech]
+ M --> C[CaptureService]
+ M --> L[LLMService] --> G[Gemini API]
+ SP --> M
+ C --> M
+ L --> M
+```
+
+### Data flow and IPC flow
+
+```mermaid
+sequenceDiagram
+ participant U as User
+ participant R as Renderer
+ participant M as Main process
+ participant X as Speech or Capture service
+ participant L as LLM service
+ participant G as Gemini
+ U->>R: Chat, microphone, hotkey, or screen question
+ R->>M: Preload IPC request / PCM chunks
+ M->>X: Capture or transcribe
+ X-->>M: Transcript or image buffer
+ M->>L: Profile, session context, request
+ L->>G: Streamed generation
+ G-->>L: Answer tokens
+ L-->>M: Formatted response
+ M-->>R: IPC response events
+```
+
+Renderer pages use `preload.js`; the main process owns settings, windows, capture, speech, Gemini requests, and broadcasts.
+
+### Architecture assessment
+
+| Area | Finding | Recommended improvement |
+|---|---|---|
+| Main process | `main.js` owns IPC, shortcuts, settings, speech orchestration, LLM work, and lifecycle logic. | Split into request, settings, shortcut, and lifecycle controllers. |
+| Services | Speech, window, and LLM services are very large modules. | Separate state machines, transport adapters, and rendering concerns. |
+| Gemini latency | Retry, fallback-model, SDK, and alternate-HTTPS paths can compound failure latency. | Use one retry/circuit-breaker policy and request cancellation. |
+| Screenshots | Full-screen PNGs are base64 encoded and uploaded. | Crop/downscale and use JPEG where text fidelity permits. |
+| Memory | Event count is bounded, but byte size is not; consolidation can be expensive. | Use a byte budget, rolling summary, and last 20–40 turns. |
+| Background work | Screen/window/always-on-top polling creates recurring wakeups. | Pause polling while hidden and prefer event-driven behavior. |
+| UI | Large HTML files contain inline styles and behavior. | Incrementally extract shared components and styles. |
+| Tests | No automated test suite is declared. | Add unit, IPC-contract, and Electron smoke tests. |
+
+### Security and Electron review
+
+Current strengths: `contextIsolation` is enabled, Node integration is disabled, the remote module is disabled, local navigation is guarded, and logging redacts common secret-shaped fields.
+
+Priority work:
+
+1. Do not return Gemini or Azure API keys to renderer windows; return only configured status or a masked suffix.
+2. Store packaged-app secrets in macOS Keychain/Electron `safeStorage`, not plaintext `.env`.
+3. Disable DevTools outside development.
+4. Validate every IPC payload and verify the sender for privileged operations.
+5. Add strict Content Security Policy headers to all local renderer pages.
+6. Enable hardened runtime, signing, and notarization before distributing a macOS app.
+7. Recover individual services after faults rather than treating all uncaught exceptions as survivable.
+
+### Gemini and Azure Speech optimization
+
+- Reuse a shared HTTPS keep-alive agent and cancel timed-out/stale Gemini requests with request IDs and `AbortController`.
+- Measure capture, transcription, prompt construction, first-token, and completion latency independently.
+- Fail over immediately on model availability/quota errors; do not retry invalid keys or malformed input.
+- Keep one normalized prompt contract for typed, spoken, and screenshot questions.
+- Benchmark Azure end-silence around 700–1,000 ms for faster interview responses.
+- Add profile-specific Azure phrase lists for terms such as VLAN, RAID, IAM, EC2, Kubernetes, Terraform, and Playwright.
+- Add explicit speech states: `idle → starting → listening → finalizing → error`.
+- Apply IPC audio chunk limits and backpressure; never enable audio logging by default.
+
+### Latency metrics
+
+Settings → **Performance** displays the most recent in-app timing summary. The app records speech transcription duration, Gemini first-token time, full LLM time, prompt size, cache hits, and speech-to-answer time. These measurements make it possible to distinguish local overhead from Azure or Gemini network latency.
+
+### Immediate roadmap
+
+1. Protect API keys and validate IPC payloads.
+2. Compress screenshots and cancel stale Gemini work.
+3. Simplify retry/fallback behavior and reuse connections.
+4. Reduce polling, improve normal quit/tray behavior, and instrument latency.
+5. Add smoke tests for startup, profile switching, settings, speech, and screenshot error states.
+
+### Long-term target
+
+```mermaid
+flowchart TB
+ R[Renderer surfaces] --> I[Typed IPC contract]
+ I --> Q[Request Coordinator]
+ Q --> P[Profile and Prompt Engine]
+ Q --> S[Speech Coordinator]
+ Q --> C[Capture Coordinator]
+ Q --> G[Gemini Gateway]
+ Q --> M[Bounded Session Store]
+ I --> K[Secure Settings Store]
+ W[Window Lifecycle Manager] --> R
+```
+
+The target is a single, validated request pipeline shared by chat, voice, and screenshots, with consistent cancellation, prompt construction, metrics, error handling, and streamed output.
diff --git a/chat.html b/chat.html
index b0f68c4f..d6997753 100644
--- a/chat.html
+++ b/chat.html
@@ -1005,7 +1005,6 @@
}
hideListeningAnimation();
- addMessage('Stopped Listening', 'system');
}
function handleTranscription(text) {
@@ -1013,15 +1012,10 @@
// Hide listening animation first
hideListeningAnimation();
- // Show transcribed text with slight delay for smooth transition
- setTimeout(() => {
- addMessage(text.trim(), 'transcription');
-
- // Show thinking indicator after transcription
- setTimeout(() => {
- showThinkingIndicator();
- }, 300);
- }, 200);
+ // A final Azure result is already stable. Render it immediately;
+ // cosmetic delays make voice input feel unresponsive.
+ addMessage(text.trim(), 'transcription');
+ showThinkingIndicator();
} else {
console.warn('Invalid or empty transcription text - ignoring:', text);
}
@@ -1170,8 +1164,6 @@
// Listen for speech status
whysperAPI.onSpeechStatus((event, data) => {
if (data && data.status) {
- addMessage(data.status, 'system');
-
if (data.status.includes('started') || data.status.includes('Recording')) {
handleRecordingStarted();
} else if (data.status.includes('stopped') || data.status.includes('ended')) {
@@ -1180,6 +1172,12 @@
}
});
+ whysperAPI.onPracticeMuteState?.((event, data) => {
+ addMessage(data?.muted
+ ? 'Microphone paused — release Space to resume.'
+ : 'Microphone resumed.', 'system');
+ });
+
// Listen for speech errors
whysperAPI.onSpeechError((event, data) => {
if (data && data.error) {
diff --git a/docs/V1_IMPLEMENTATION_PLAN.md b/docs/V1_IMPLEMENTATION_PLAN.md
new file mode 100644
index 00000000..98290523
--- /dev/null
+++ b/docs/V1_IMPLEMENTATION_PLAN.md
@@ -0,0 +1,142 @@
+# OpenCluely V1 Implementation Plan
+
+## Goal
+
+Turn OpenCluely into a reliable local interview-practice and knowledge assistant before expanding it into a full universal skill platform.
+
+V1 is successful when text chat, Azure microphone capture, screenshot capture, streaming responses, diagnostics, and the Amazon DCT profile work reliably through `npm start` on macOS.
+
+## Current Architecture Map
+
+```mermaid
+flowchart LR
+ UI[Main, Chat, Settings, Response Windows] --> PRE[preload IPC bridge]
+ PRE --> MAIN[ApplicationController]
+ MAIN --> SPEECH[Azure Speech / Whisper]
+ MAIN --> CAPTURE[Screen Capture]
+ MAIN --> LLM[Gemini]
+ MAIN --> SESSION[Session Manager]
+ SESSION --> PROMPTS[Profile Prompts]
+ LLM --> UI
+```
+
+## Current Data Flow
+
+```mermaid
+sequenceDiagram
+ participant User
+ participant Speech as Azure Speech
+ participant Main as Electron Main
+ participant AI as Gemini
+ participant UI as Chat / Overlay
+ User->>Speech: Speak question
+ Speech->>Main: Final transcript
+ Main->>AI: Profile prompt + short history
+ AI-->>Main: Streamed answer
+ Main-->>UI: Incremental response chunks
+```
+
+## V1 Scope
+
+### 1. Reliability baseline — in progress
+
+- [x] Add Amazon DCT prompt and question classification.
+- [x] Add Gemini model selection and visible Gemini quota errors.
+- [x] Add a diagnostics location and copy/open-log controls.
+- [x] Add log redaction for API keys going forward.
+- [x] Correct the macOS microphone audio path to send 16 kHz PCM to Azure Speech.
+- [x] Add Azure audio-pipeline diagnostics.
+- [x] Add actionable screen-capture permission errors.
+- [ ] Validate live microphone transcription using `npm start`.
+- [ ] Validate screen capture using `npm start`.
+- [ ] Remove legacy logging that can expose credentials and rotate existing keys.
+
+### 2. Performance observability
+
+- [ ] Add one request ID spanning speech, Gemini, and UI rendering.
+- [ ] Record STT, first-token, full-response, rendering, and end-to-end latency.
+- [ ] Add a compact diagnostics view with recent errors and timings.
+- [ ] Prevent duplicate retry paths after quota or network failures.
+
+### 3. Universal skill foundation
+
+- [ ] Replace hard-coded skill arrays with a skill registry.
+- [ ] Define a manifest format: prompt, knowledge scope, response modes, language rules, and model preference.
+- [ ] Migrate DSA and Amazon DCT to manifests.
+- [ ] Add profile switching without restarting the application.
+- [ ] Add response modes: Quick, Interview, Detailed, STAR, and Troubleshooting.
+
+### 3A. First profile catalogue — in progress
+
+- [x] Amazon DCT profile.
+- [x] DevOps profile.
+- [x] SDET profile.
+- [x] Backend Engineer profile.
+- [x] STAR response mode.
+- [x] Leadership Principles mode.
+- [ ] Add the remaining profiles only after reliability tests pass.
+
+### 4. Prompt composition
+
+- [ ] Compose prompts from Global Rules + Skill + Interview Profile + Company + User Preferences.
+- [ ] Keep quick-answer prompts small enough for low latency.
+- [ ] Add safe defaults for context limits and response token limits.
+- [ ] Add prompt-version metadata to diagnostics.
+
+### 5. Security and production readiness
+
+- [ ] Remove the custom TLS certificate-verification bypass.
+- [ ] Validate every IPC payload at the main-process boundary.
+- [ ] Restrict privileged IPC to the minimum necessary surface.
+- [ ] Separate session history, diagnostics, and settings storage.
+- [ ] Add automated tests for prompt composition, configuration, and speech/capture error handling.
+
+## Explicitly Deferred from V1
+
+- RAG, PDF ingestion, embeddings, and a local vector database.
+- A large catalogue of role profiles.
+- Full UI redesign.
+- Signed and notarized release builds.
+
+These begin only after the V1 reliability baseline is verified.
+
+## Current Test Workflow
+
+Run locally:
+
+```bash
+npm start
+```
+
+Then verify:
+
+1. Text chat: ask “What is DNS?”
+2. Microphone: speak “What is DNS?”, then pause.
+3. Screenshot: use `Cmd+Shift+S` while a visible question is on screen.
+4. Diagnostics: Settings → Open Logs / Copy Diagnostics.
+
+## Rules for This Development Phase
+
+- Do not create a release build until the three primary workflows pass locally.
+- Do not commit or push partial work until the V1 test checklist passes.
+- Never put API keys, transcripts, or retrieved private documents into logs.
+- Do not expand the skill catalogue while audio and screen capture remain unreliable.
+# Phase 8 — UI/UX Redesign
+
+Implemented locally (not yet committed): skill and language selection; interview company selection; Quick, Interview, Detailed, STAR, and Troubleshooting response formats; persisted dark/light appearance; and compact layout density. The active response format is supplied to Gemini as a system-level instruction for every interview profile.
+
+# Phase 5 — Interview Mode Engine
+
+Implemented locally: Amazon DCT, SDET, and DevOps profiles define their knowledge areas and response styles in a central profile registry. Each profile loads its own prompt, can be switched from Settings or the overlay navigation, and is validated before it becomes the active skill.
+
+# Phase 4 — Programming and Platform Expansion
+
+Implemented locally: the DSA language selector supports Python, Java, JavaScript, TypeScript, Go, Rust, C, C++, C#, Kotlin, Swift, PHP, Ruby, Bash, and PowerShell. Settings also provide optional technical-focus selectors for MySQL, PostgreSQL, MSSQL, Oracle, MongoDB, Redis, Elasticsearch, Cassandra, DynamoDB; AWS, Azure, GCP; Docker, Kubernetes, OpenShift; and Terraform, Ansible, Jenkins, and GitHub Actions. Selected focus is persisted and added to interview prompts when relevant.
+
+# Phase 2 — Response Latency Optimization
+
+Implemented locally: streamed Gemini output is incrementally rendered and throttled to avoid excessive IPC/UI updates; repeated short factual questions use a bounded ten-minute in-memory cache; Gemini HTTPS connections are reused; voice coalescing is reduced to 450 ms; and the Settings Performance view reports STT, first-token, full LLM, renderer, cache, and speech-to-answer timings. External Azure and Gemini service time still determines the practical lower bound.
+
+# Phase 3 — Universal Skill System
+
+Implemented locally: a declarative skill catalog now owns skill system prompts, knowledge scopes, response style, display format, latency preferences, language preferences, aliases, and categories. Static prompt files remain supported as overrides. Settings and overlay navigation load their available skills from the same catalog, covering interview, general, education, and general-AI skills.
diff --git a/docs/engineering/AUDIT_REPORT.md b/docs/engineering/AUDIT_REPORT.md
new file mode 100644
index 00000000..26f216de
--- /dev/null
+++ b/docs/engineering/AUDIT_REPORT.md
@@ -0,0 +1,72 @@
+# OpenCluely V3 Beta Engineering Audit
+
+Date: 2026-08-16
+Scope: static review of the Electron main process, preload bridge, renderers, services, managers, configuration, dependencies, and existing metrics. This report does not claim runtime measurements that were not collected from a controlled test run.
+
+## Architecture
+
+```mermaid
+flowchart LR
+ UI["Renderer windows\nOverlay · Chat · Settings · Response"] --> PRE["preload.js\ncontextBridge / IPC"]
+ PRE --> MAIN["main.js\nApplicationController"]
+ MAIN --> WIN["WindowManager\nBrowserWindow lifecycle"]
+ MAIN --> SES["SessionManager\nbounded in-memory history"]
+ MAIN --> CAP["CaptureService\nElectron + macOS fallback"]
+ MAIN --> SPEECH["SpeechService\nAzure / Whisper"]
+ MAIN --> LLM["LLMService\nGemini streaming + cache"]
+ MAIN --> METRICS["PerformanceMetrics\nin-memory rolling sample"]
+ SPEECH --> AZURE[Azure Speech]
+ LLM --> GEMINI[Gemini API]
+```
+
+## Startup and shutdown flow
+
+1. `main.js` resolves the user-data `.env`, loads configuration, then creates services and managers.
+2. Electron readiness creates the configured windows and installs IPC handlers.
+3. Settings load the active role, candidate context, job context, provider, and response preferences.
+4. Speech and Gemini are initialized lazily or on setting changes.
+5. On `will-quit`, global shortcuts are removed, speech shuts down, and windows are destroyed.
+
+Strengths: state persistence is local; the Gemini client is reused; the response cache is bounded; renderer isolation is on.
+Gaps: startup duration is not timed; shutdown is not awaited or bounded; global crash guards can leave the process running after corruption.
+
+## IPC flow
+
+```mermaid
+sequenceDiagram
+ participant R as Renderer
+ participant P as preload
+ participant M as Main
+ participant S as Service
+ R->>P: invoke/send allowlisted action
+ P->>M: IPC request
+ M->>S: capture / speech / LLM / settings action
+ S-->>M: result or streamed delta
+ M-->>P: IPC event
+ P-->>R: renderer callback
+```
+
+The preload bridge avoids direct Node exposure, but it exposes a large set of privileged actions. Most listener registrations do not return an unsubscribe function, so repeated renderer initialization can accumulate event listeners.
+
+## Findings
+
+| Priority | Finding | Root cause | Impact | Fix / effort |
+|---|---|---|---|---|
+| High | Global uncaught exception and rejection handlers keep the process alive | Catch-all handlers log but do not transition the app into a known-safe state | A corrupted service can continue running with stale resources | Add health state, stop affected service, show recovery action; 2–3 days |
+| High | Broad IPC attack surface | Many privileged handlers; generic renderer receive API; limited per-sender validation | Compromised renderer has more capabilities than needed | Define channel schemas and sender/window checks; 3–5 days |
+| High | Recurring overlay enforcement timers | Per-window 3-second interval plus blur/show/focus timer fan-out | Idle CPU wakeups and timer lifecycle complexity | Centralize one scheduler, clear on close; 2–3 days |
+| Medium | Incomplete runtime observability | Metrics track durations only, in memory, with no process memory/CPU or startup spans | Cannot prove latency or 8-hour stability targets | Add process/resource snapshots and JSON diagnostics; 2–3 days |
+| Medium | Session-manager initialization stores every prompt | All Markdown prompts become system events at startup | Avoidable memory and startup work as catalogue grows | Load only active prompt; fetch others lazily; 1–2 days |
+| Medium | No test runner or CI quality gate | No `test` script or automated assertions | Regressions in IPC, speech, and window code reach users | Add Node unit tests then Electron integration smoke tests; 1–2 weeks |
+| Medium | Unvalidated renderer IPC payloads | Resize/move/capture/settings handlers accept renderer values | Invalid values can cause errors or unexpected resource use | Strict type/size/range schemas; 2–3 days |
+| Low | Duplicate legacy IPC paths | `invoke` and `send` variants exist for several speech/settings actions | Maintenance ambiguity and duplicate events | Deprecate one path after compatibility audit; 1–2 days |
+| Low | Static role-name maps remain as fallbacks | Dynamic catalogue is loaded at runtime but legacy maps persist | Display drift for new skills if catalogue fetch fails | Replace fallbacks with a small generic formatter; 0.5 day |
+
+## Low-risk hardening completed
+
+- Config version now reads the root `package.json`, so diagnostics no longer report a stale `1.0.0` version.
+- Packaged Electron windows now disable DevTools; local `electron .` development keeps DevTools available.
+
+## Dependency review
+
+The direct dependency tree contains Electron, electron-builder, Gemini SDK, Azure Speech SDK, Whisper capture/worker tooling, Winston logging, Markdown rendering, Prism, and Font Awesome. No direct unused dependency can be proven from static inspection alone; `markdown` and `marked` should be checked for duplicate usage before the next dependency refresh. Dependency vulnerability scanning requires a networked `npm audit` run and is not represented as a completed check here.
diff --git a/docs/engineering/BENCHMARK_REPORT.md b/docs/engineering/BENCHMARK_REPORT.md
new file mode 100644
index 00000000..6deca9c9
--- /dev/null
+++ b/docs/engineering/BENCHMARK_REPORT.md
@@ -0,0 +1,35 @@
+# Benchmark Baseline and Measurement Plan
+
+## Current evidence
+
+Existing `PerformanceMetrics` records a rolling in-memory sample of 100 named duration entries. LLM streaming already records first-token and total-response timings; speech and answer pipeline metrics are emitted by the current services. The sample is useful for a live diagnostic snapshot but is not a durable benchmark database.
+
+No controlled cold/warm startup, CPU, memory, FPS, disk-I/O, or long-run results were available in this workspace. Values must not be inferred from code or earlier interactive runs.
+
+## Required benchmark matrix
+
+| Area | Metric | Instrumentation point | Target |
+|---|---|---|---|
+| Startup | process start to ready overlay | before `app.whenReady`, after main window ready | Baseline first; reduce by 20% |
+| Speech | mic request to recognizer ready | UI click, `SpeechService` ready event | Baseline first |
+| Speech | utterance end to final transcript | Azure/Whisper segment finalization | Baseline first |
+| LLM | request build, first token, completion | existing stream spans plus request id | First useful answer under 3 s where network/model allow |
+| UI | first streamed chunk to visible paint | renderer `requestAnimationFrame` after update | Under 100 ms |
+| Memory | main/renderer RSS, heap used | `process.getProcessMemoryInfo`, `webContents.getProcessMemoryInfo` | No monotonic growth in 8-hour run |
+| CPU | idle, recording, streaming | OS sampler with process PID | Idle under 2%; recording under 10%, hardware dependent |
+| IPC | count, bytes, handler duration | wrapper around IPC dispatch | No repeated high-frequency payloads |
+
+## Benchmark protocol
+
+1. Use one macOS Intel machine and record OS version, Electron version, network type, model, and provider.
+2. Run 10 cold starts and 10 warm starts; report median, p95, and max.
+3. Run 30 short technical questions and 10 screenshot requests, with response mode and model recorded.
+4. Run a 60-minute voice session with representative pauses and record memory every minute.
+5. Repeat after each change with the same setup. Compare median and p95, not a single best result.
+
+## Immediate instrumentation backlog
+
+1. Persist metrics to an opt-in local JSONL diagnostic file with redaction.
+2. Add startup spans and per-window `did-finish-load` timings.
+3. Add resource snapshots every 60 seconds only while diagnostics are enabled.
+4. Include request id, active skill, model, output mode, and cache-hit flag; never include API keys, candidate profile, transcript, screenshot, or generated answer text.
diff --git a/docs/engineering/ERROR_HANDLING_REPORT.md b/docs/engineering/ERROR_HANDLING_REPORT.md
new file mode 100644
index 00000000..2de893df
--- /dev/null
+++ b/docs/engineering/ERROR_HANDLING_REPORT.md
@@ -0,0 +1,22 @@
+# Error Handling and Recovery Review
+
+## Current behavior
+
+Gemini error messages are normalized for quota, network, and authentication cases. Speech errors are broadcast to renderers. Logs are rotated and exceptions/rejections are recorded. Several services contain local catch blocks and fallbacks.
+
+## Gaps
+
+| Priority | Gap | Recovery design |
+|---|---|---|
+| High | Process-level error handlers only log and continue | Mark app health degraded; stop the failing subsystem; offer a controlled restart; preserve redacted diagnostic id. |
+| Medium | No unified request cancellation | Attach an abort controller to each capture/LLM request; cancel when a newer user request supersedes it or its window closes. |
+| Medium | Retries are not consistently policy-driven | Retry only transient network errors with capped exponential backoff and jitter; never retry auth/invalid-request errors. |
+| Medium | No circuit breaker for repeated provider failures | After a threshold, pause requests briefly and show provider-status recovery guidance. |
+| Low | Fallback responses can hide repeated upstream failure | Include a non-sensitive diagnostic reference and error category in the UI. |
+
+## Acceptance criteria
+
+- A network outage does not crash the process, duplicate a request, or leave the loading state stuck.
+- A speech failure releases stream/recognizer resources and allows a clean retry.
+- A window close cancels its pending UI updates.
+- Repeated fatal service failures lead to a recoverable health state, not silent continued execution.
diff --git a/docs/engineering/IPC_REPORT.md b/docs/engineering/IPC_REPORT.md
new file mode 100644
index 00000000..1aac98f4
--- /dev/null
+++ b/docs/engineering/IPC_REPORT.md
@@ -0,0 +1,30 @@
+# IPC Review
+
+## Current design
+
+`preload.js` uses `contextBridge` and does not expose Node integration. The primary API uses named `invoke`/`send` functions, and the legacy `api` bridge applies a small channel allowlist. Main-process handlers cover capture, speech, settings, logs, diagnostics, windows, session history, model diagnostics, and installer actions.
+
+## Risks and actions
+
+| Priority | Risk | Recommended change |
+|---|---|---|
+| High | A renderer can invoke many privileged actions without a central sender check | Introduce `assertKnownRenderer(event, allowedWindowTypes)` before sensitive handlers. |
+| High | Arbitrary-size buffers can be sent through `audio-chunk` | Enforce a maximum chunk byte size and drop malformed/non-binary payloads before `Buffer.from`. |
+| Medium | Window move/resize and capture-area inputs are renderer-controlled | Validate finite numbers, bounds, display ids, and maximum capture dimensions in main. |
+| Medium | Many event subscription helpers lack unsubscribe support | Every `on…` preload method should return a removal function, as `onInstallProgress` already does. |
+| Low | Duplicate `send` and `invoke` variants blur request semantics | Standardize on `invoke` for request-response and events for streams; remove legacy handlers in a compatibility release. |
+
+## Payload policy for V3
+
+- Strings: normalize and cap size before service calls.
+- Audio: fixed maximum frame size and sampling metadata, no unbounded queue.
+- Images: enforce image byte/pixel caps before LLM submission.
+- Settings: allow only known keys and typed ranges.
+- Logs: redact secrets and user-content by default.
+
+## Acceptance tests
+
+1. Unknown renderer/window cannot invoke privileged handlers.
+2. Oversize audio/image/settings payload returns a structured error without process memory growth.
+3. Reopening Chat or Settings 100 times does not grow listener count.
+4. Streamed LLM chunks remain ordered and stop after a request is cancelled.
diff --git a/docs/engineering/MASTER_OPTIMIZATION_ROADMAP.md b/docs/engineering/MASTER_OPTIMIZATION_ROADMAP.md
new file mode 100644
index 00000000..9cccc727
--- /dev/null
+++ b/docs/engineering/MASTER_OPTIMIZATION_ROADMAP.md
@@ -0,0 +1,45 @@
+# Master Optimization Roadmap
+
+## Phase A — Stabilize the execution boundary (High, 1–2 weeks)
+
+1. Centralize window scheduler and clear all intervals/listeners on close.
+2. Add IPC schemas, sender authorization, audio/image limits, and unsubscribe-capable renderer listeners.
+3. Replace global “keep alive” fatal handlers with subsystem health/degraded-state recovery.
+4. Add startup, shutdown, process-resource, and per-window timing spans.
+
+Expected outcome: fewer hangs, lower idle wakeups, bounded resource lifecycle, and actionable failures.
+
+## Phase B — Establish measurable quality (High, 1–2 weeks)
+
+1. Add a Node test runner for pure modules and an Electron smoke test runner.
+2. Build repeatable cold/warm startup, voice, LLM, UI, memory, and CPU benchmarks.
+3. Add one-hour stress automation: window cycles, mock stream chunks, API errors, and cancellation.
+4. Run `npm audit` and create a dependency-update policy.
+
+Expected outcome: a defensible performance baseline and regressions caught before packaging.
+
+## Phase C — Reduce end-to-end latency (Medium, 1–2 weeks)
+
+1. Use persisted metrics to identify the dominant latency segment; do not optimize blind.
+2. Lazily load non-active skill prompts and reduce session initialization work.
+3. Keep current Gemini streaming and cache; add cancellation/timeout propagation.
+4. Batch renderer updates to animation frames and verify no extra resize/repaint cycles.
+
+Expected outcome: faster first visible answer and fewer unnecessary CPU wakeups.
+
+## Phase D — Security and distribution (Medium, 1–3 weeks)
+
+1. Add CSP and remove unsafe inline execution progressively.
+2. Move packaged API secrets to OS credential storage.
+3. Sign/notarize macOS builds; add artifact provenance and release checklist.
+4. Remove remaining legacy stealth terminology/paths during a compatibility review.
+
+## Phase E — Long-running reliability (Low, ongoing)
+
+1. Execute 6-, 12-, and 24-hour provider-aware soak tests.
+2. Alert on heap/RSS slope, listener counts, audio context counts, error rate, and request queue depth.
+3. Establish performance budgets in CI from Phase B baselines.
+
+## Prioritization principle
+
+Do not add more features until Phase A and Phase B have an automated safety net. Optimizations must be driven by measured p50/p95 latency and resource data, not single-run impressions.
diff --git a/docs/engineering/PERFORMANCE_PROFILE.md b/docs/engineering/PERFORMANCE_PROFILE.md
new file mode 100644
index 00000000..a52ef6b7
--- /dev/null
+++ b/docs/engineering/PERFORMANCE_PROFILE.md
@@ -0,0 +1,25 @@
+# Static Performance Profile
+
+## Likely hot paths to measure first
+
+1. **WindowManager enforcement:** recurring 3-second timers are installed per window, alongside delayed focus/show/blur enforcement. Measure idle wakeups and verify interval cleanup.
+2. **Audio path:** renderer `ScriptProcessor` callbacks serialize PCM to main through IPC. Measure chunks/second, bytes/second, queue length, and main-process processing time.
+3. **Speech segmentation:** VAD/segment timers determine when transcription reaches the LLM. Measure voice-end to final transcript separately from model latency.
+4. **LLM streaming:** request construction includes system prompt, role preferences, and bounded history; chunk rendering is throttled to roughly 33 ms. Measure prompt characters, first token, completion, and renderer paint.
+5. **Window resize/reposition:** streaming answers may drive resize operations. Measure resize count per response and coalesce updates if needed.
+
+## Existing positive controls
+
+- Gemini client is reused and uses a keep-alive HTTPS agent.
+- Definition-style responses can be cached with a bounded 100-entry, 10-minute cache.
+- Streaming deltas are throttled before renderer delivery.
+- Voice interview history is bounded more tightly than general history.
+
+## Do not optimize before measuring
+
+- Replacing Azure Speech or Gemini model/provider.
+- Adding worker threads.
+- Compressing IPC payloads.
+- Removing renderer audio processing.
+
+Each has functional or latency trade-offs and needs evidence from the benchmark plan.
diff --git a/docs/engineering/PRODUCTION_READINESS_REPORT.md b/docs/engineering/PRODUCTION_READINESS_REPORT.md
new file mode 100644
index 00000000..0f4e04c1
--- /dev/null
+++ b/docs/engineering/PRODUCTION_READINESS_REPORT.md
@@ -0,0 +1,26 @@
+# Production Readiness Report
+
+## Status: beta, not production-ready
+
+The app has working foundations—renderer isolation, local settings, reusable Gemini client, bounded LLM cache, streaming, rotated/redacted logs, and explicit speech cleanup—but it lacks the evidence and hardening required for a production release.
+
+## Release gates
+
+| Gate | Status | Requirement |
+|---|---|---|
+| Static syntax checks | Passing | Run before every commit. |
+| Unit/integration test suite | Missing | Add CI and baseline coverage. |
+| End-to-end smoke test | Manual only | Automate core Electron launch/window/settings flows. |
+| 1-hour stress test | Missing | No crashes, bounded memory, no listener growth. |
+| 8-hour soak test | Missing | Required before stable release. |
+| Security IPC/CSP hardening | Incomplete | Resolve high findings in security report. |
+| Dependency vulnerability scan | Not measured | Run `npm audit` in a networked CI environment. |
+| macOS signing/notarization | Missing | Required for public production distribution. |
+| Crash recovery policy | Incomplete | Implement degraded-state recovery and safe restart. |
+
+## Safe beta operating model
+
+- Run locally with `npm start` during validation.
+- Use for authorised preparation and development only.
+- Treat Gemini/Azure network failures as recoverable feature failures, not application failures.
+- Do not create a public release until the gates above have recorded evidence.
diff --git a/docs/engineering/SECURITY_REPORT.md b/docs/engineering/SECURITY_REPORT.md
new file mode 100644
index 00000000..e99252d4
--- /dev/null
+++ b/docs/engineering/SECURITY_REPORT.md
@@ -0,0 +1,24 @@
+# Security Review
+
+## Verified controls
+
+- Browser windows use `nodeIntegration: false` and `contextIsolation: true`.
+- External web navigation is routed to the system browser and popup creation is denied.
+- API keys are stored locally and logger redaction covers common key/token fields.
+- Candidate and target-job text is labeled as reference data in the model prompt, mitigating instruction injection from pasted material.
+- V3 hardening disables DevTools in packaged windows.
+
+## Findings
+
+| Priority | Finding | Impact | Remediation |
+|---|---|---|---|
+| High | Content Security Policy is not visibly defined in local HTML pages | A future script injection bug has wider renderer impact | Add restrictive CSP (`default-src 'self'`; explicit style/font/image allowances) and remove unsafe inline script/style gradually. |
+| High | IPC validation and sender authorization are incomplete | A compromised renderer may request privileged main actions | Add typed handler wrappers and per-window authorization. |
+| Medium | Secrets are persisted in a local `.env` plaintext file | Local account compromise exposes API keys | Document OS account protection; migrate secrets to Keychain/Credential Manager for packaged builds. |
+| Medium | Global error handling retains process after fatal errors | Security-sensitive partial failures can leave an unknown state | Mark health degraded and restart or disable the failing subsystem. |
+| Medium | No signed/notarized macOS distribution pipeline | Users cannot establish binary provenance | Add code signing and notarization before public production release. |
+| Low | Some legacy naming/configuration still refers to stealth behavior | It conflicts with the authorised-preparation product boundary | Remove or rename legacy implementation and documentation in a dedicated compatibility review. |
+
+## Security release gate
+
+Before a public non-beta release: zero known high-severity dependency advisories; IPC schema tests pass; CSP is enabled; packaged DevTools remain disabled; secret redaction tests pass; and signed distribution is configured.
diff --git a/docs/engineering/TEST_PLAN.md b/docs/engineering/TEST_PLAN.md
new file mode 100644
index 00000000..c61d56f5
--- /dev/null
+++ b/docs/engineering/TEST_PLAN.md
@@ -0,0 +1,25 @@
+# V3 Beta Test Plan
+
+## Test layers
+
+| Layer | Scope | Initial target |
+|---|---|---|
+| Unit | skill catalogue, prompt loader, profile normalization, cache keys, metrics aggregation, IPC validators | 80% of pure modules |
+| Integration | settings persistence, Gemini request construction, session bounds, capture fallback selection | Critical-path coverage |
+| Electron smoke | app startup, window load, settings open/close, chat send, mic start/stop | macOS Intel and Apple Silicon |
+| Manual provider | Azure valid/invalid key, Gemini valid/invalid key, network loss | Every beta candidate |
+| Stress | repeated window lifecycle, simulated audio chunks, cache pressure, request cancellation | 1 hour before release |
+
+## Regression scenarios
+
+1. Start with no keys: onboarding/settings remains usable and no crash occurs.
+2. Save role, response mode, language, candidate profile, and target job; restart and verify each persists.
+3. Switch every catalogue category and send a text question.
+4. Start/stop microphone repeatedly; verify no duplicate transcript and no growing listener count.
+5. Trigger screenshot capture with permission granted and denied; verify actionable UI error.
+6. Simulate Gemini timeout, quota error, invalid key, and offline network; verify one useful message and recovery on next request.
+7. Open/close Chat and Settings 100 times; record process memory before and after.
+
+## Coverage statement
+
+Current automated coverage: not established; no test runner is configured. A numeric coverage target is therefore not yet meaningful. Add the test framework and report line/branch/function coverage from CI rather than asserting 90% without evidence.
diff --git a/index.html b/index.html
index 31e37f5d..af551df6 100644
--- a/index.html
+++ b/index.html
@@ -76,6 +76,11 @@
animation: pulse 2s infinite;
}
+ .command-item.muted i {
+ color: #fbbf24;
+ text-shadow: 0 0 10px rgba(251, 191, 36, 0.55);
+ }
+
.command-item.active {
color: #4caf50;
text-shadow: 0 1px 2px rgba(76, 175, 80, 0.3);
@@ -358,30 +363,22 @@
⌘⇧S
-
diff --git a/llm-response.html b/llm-response.html
index 3a4276f4..caee4ed7 100644
--- a/llm-response.html
+++ b/llm-response.html
@@ -475,6 +475,8 @@
let isInteractive = false;
let scrollableElements = [];
let initialized = false;
+ let streamingMessageId = null;
+ let streamingResponse = '';
// Immediate logging to verify script execution
console.log('[LLM-RESPONSE] Script tag executed');
@@ -532,6 +534,20 @@
console.log('[LLM-RESPONSE] show-loading received');
showLoadingState();
});
+
+ // Voice responses already stream from Gemini. Render plain
+ // text immediately, then let the final event replace it with
+ // formatted Markdown once generation is complete.
+ window.electronAPI.onTranscriptionLlmResponseStart?.((_event, data) => {
+ streamingMessageId = data?.messageId || null;
+ streamingResponse = '';
+ showLoadingState();
+ });
+ window.electronAPI.onTranscriptionLlmResponseChunk?.((_event, data) => {
+ if (!data?.messageId || data.messageId !== streamingMessageId) return;
+ streamingResponse += data.delta || '';
+ displayStreamingText(streamingResponse);
+ });
// Listen for LLM response
window.electronAPI.onDisplayLlmResponse(function() {
@@ -560,6 +576,8 @@
hideLoadingState();
displayResponse(actualData);
+ streamingMessageId = null;
+ streamingResponse = '';
setupScrolling();
setTimeout(verifyDisplayState, 500);
console.log('[LLM-RESPONSE] Handler completed successfully');
@@ -602,6 +620,22 @@
}
}
+ function displayStreamingText(text) {
+ const responseElement = document.getElementById('response-content');
+ const splitLayout = document.getElementById('split-layout');
+ const fullLayout = document.getElementById('full-content');
+ const fullMarkdown = document.getElementById('full-markdown');
+ if (!responseElement || !fullLayout || !fullMarkdown) return;
+
+ hideLoadingState();
+ responseElement.classList.remove('hidden');
+ splitLayout?.classList.add('hidden');
+ fullLayout.classList.remove('hidden');
+ // Do not parse partial Markdown on each stream chunk. It is both
+ // faster and avoids flicker from incomplete lists/code fences.
+ fullMarkdown.textContent = text;
+ }
+
function renderMarkdown(text) {
if (typeof marked !== 'undefined') {
return marked.parse ? marked.parse(text) : marked(text);
diff --git a/main.js b/main.js
index 36ccf4bb..fbb4e817 100644
--- a/main.js
+++ b/main.js
@@ -1,7 +1,7 @@
const path = require("path");
const fs = require("fs");
const { fileURLToPath } = require("url");
-const { app, BrowserWindow, globalShortcut, session, ipcMain } = require("electron");
+const { app, BrowserWindow, globalShortcut, session, ipcMain, systemPreferences } = require("electron");
// ── Resolve a stable .env location ──
// In packaged builds process.cwd() is unstable and frequently read-only
@@ -46,6 +46,22 @@ function formatEnvValue(raw) {
return `"${v.replace(/"/g, '\\"')}"`;
}
+// Candidate and job material can contain newlines, which are not safe in a
+// dotenv key=value record. Store these two optional local settings as base64
+// instead; they are decoded only in memory before a relevant Gemini request.
+function decodeStoredProfile(value) {
+ if (!value) return "";
+ try {
+ return Buffer.from(String(value), "base64").toString("utf8").trim();
+ } catch (_) {
+ return "";
+ }
+}
+
+function normalizeProfileText(value, limit = 12000) {
+ return typeof value === "string" ? value.replace(/\u0000/g, "").trim().slice(0, limit) : "";
+}
+
// ── Linux GPU process crash workaround ──
// On many Linux setups (Wayland, X11 without GPU drivers, Docker, headless,
// or systems with broken Mesa/NVIDIA stacks), Chromium's GPU process crashes
@@ -75,8 +91,10 @@ app.commandLine.appendSwitch("disable-component-update");
app.commandLine.appendSwitch("disable-domain-reliability");
app.commandLine.appendSwitch("no-pings");
-const logger = require("./src/core/logger").createServiceLogger("MAIN");
+const appLogger = require("./src/core/logger");
+const logger = appLogger.createServiceLogger("MAIN");
const config = require("./src/core/config");
+const performanceMetrics = require("./src/core/performance-metrics");
const FirstRunManager = require("./src/core/first-run");
// ── Global crash guard ──
@@ -107,15 +125,41 @@ const llmService = require("./src/services/llm.service");
// Managers
const windowManager = require("./src/managers/window.manager");
const sessionManager = require("./src/managers/session.manager");
+const { getNavigableProfileIds, normalizeProfileId, isSupportedSkill } = require('./src/skills/profile-registry');
+const { skills: skillCatalog } = require('./src/skills/skill-catalog');
+const { isSupportedTechnology } = require('./src/skills/technology-registry');
class ApplicationController {
constructor() {
this.isReady = false;
this.starting = false;
- this.activeSkill = "dsa";
- // Default to C++ so language is enforced from first run
- this.codingLanguage = "cpp";
+ const savedSkill = normalizeProfileId(process.env.ACTIVE_SKILL || "amazon-dct");
+ this.activeSkill = isSupportedSkill(savedSkill) ? savedSkill : "amazon-dct";
+ // Default to C++ on first run, but retain the last language selected in
+ // Settings on every later launch.
+ this.codingLanguage = process.env.CODING_LANGUAGE || "cpp";
+ this.interviewCompany = process.env.INTERVIEW_COMPANY || "general";
+ this.responseMode = process.env.RESPONSE_MODE || "interview";
+ this.uiTheme = process.env.UI_THEME || "dark";
+ this.compactMode = process.env.COMPACT_MODE === "true";
+ this.appIcon = process.env.APP_ICON || "terminal";
+ this.technologyContext = {
+ database: process.env.TECH_DATABASE || 'auto', cloud: process.env.TECH_CLOUD || 'auto',
+ containers: process.env.TECH_CONTAINERS || 'auto', infrastructure: process.env.TECH_INFRASTRUCTURE || 'auto'
+ };
+ this.candidateProfile = decodeStoredProfile(process.env.CANDIDATE_PROFILE_B64);
+ this.targetJobProfile = decodeStoredProfile(process.env.TARGET_JOB_PROFILE_B64);
+ llmService.setResponsePreferences({
+ company: this.interviewCompany,
+ responseMode: this.responseMode,
+ technologyContext: this.technologyContext,
+ candidateProfile: this.candidateProfile,
+ targetJobProfile: this.targetJobProfile
+ });
this.speechAvailable = false;
+ const savedWindowGap = Number(process.env.WINDOW_GAP);
+ if (Number.isFinite(savedWindowGap)) windowManager.setWindowGap(savedWindowGap);
+ sessionManager.setActiveSkill(this.activeSkill);
// Utterance coalescing: VAD emits a transcript per natural pause, but a
// single spoken question can still arrive as a few fragments (mid-thought
@@ -124,7 +168,12 @@ class ApplicationController {
this._utteranceBuffer = "";
this._utteranceTimer = null;
this._utteranceDispatchInFlight = false;
- this._utteranceCoalesceMs = 800;
+ // Azure final results already represent a natural phrase boundary. Keep a
+ // very small merge window for rare back-to-back fragments, rather than
+ // adding a perceptible half-second pause before every Gemini request.
+ this._utteranceCoalesceMs = 180;
+ this._utteranceStartedAt = null;
+ this._speechRecordingStartedAt = null;
// First-run onboarding: detects missing .env / API key and triggers
// a settings-window prompt on first launch so users don't have to
@@ -261,6 +310,7 @@ class ApplicationController {
await windowManager.initializeWindows({ showMainWindow: !isFirstRun });
this.setupGlobalShortcuts();
+ this.setupPracticePushToTalk();
// Initialize default stealth mode with terminal icon
this.updateAppIcon("terminal");
@@ -394,6 +444,8 @@ class ApplicationController {
"CommandOrControl+Shift+V": () => windowManager.toggleVisibility(),
"CommandOrControl+Shift+I": () => windowManager.toggleInteraction(),
"CommandOrControl+Shift+C": () => windowManager.switchToWindow("chat"),
+ "CommandOrControl+Shift+A": () => this.startInterviewMode(),
+ "CommandOrControl+Q": () => app.quit(),
"CommandOrControl+Shift+\\": () => this.clearSessionMemory(),
"CommandOrControl+,": () => windowManager.showSettings(),
"Alt+A": () => windowManager.toggleInteraction(),
@@ -416,16 +468,105 @@ class ApplicationController {
});
}
+ /**
+ * Practice-only hold-to-mute for the compact toolbar. Electron cannot
+ * observe key-up events globally on macOS, so this intentionally works only
+ * while an OpenCluely non-editable surface has focus. Holding Space pauses
+ * capture; releasing it resumes capture.
+ */
+ setupPracticePushToTalk() {
+ this._pushToTalkHeld = false;
+ this._pushToTalkPausedRecording = false;
+ this._pushToTalkAwaitingStop = false;
+ this._pushToTalkResumeRequested = false;
+ const handleInput = (event, input) => {
+ const isSpace = input?.code === 'Space' || input?.key === ' ' || input?.key === 'Spacebar';
+ if (!isSpace || input?.isAutoRepeat) return;
+
+ if (input.type === 'keyDown') {
+ event.preventDefault();
+ if (this._pushToTalkHeld) return;
+ this._pushToTalkHeld = true;
+ const status = speechService.getStatus();
+ this._pushToTalkPausedRecording = !!status.isRecording;
+ if (this._pushToTalkPausedRecording) {
+ this._pushToTalkAwaitingStop = true;
+ windowManager.broadcastToAllWindows('practice-mute-state', { muted: true });
+ speechService.stopRecording();
+ logger.info('Practice hold-to-mute paused microphone');
+ }
+ return;
+ }
+
+ if (input.type === 'keyUp') {
+ event.preventDefault();
+ const shouldResume = this._pushToTalkHeld && this._pushToTalkPausedRecording;
+ this._pushToTalkHeld = false;
+ this._pushToTalkPausedRecording = false;
+ if (shouldResume) {
+ // Azure stop is asynchronous. Starting a new recognizer before the
+ // old one has finished can make its completion handler tear down the
+ // new session, so defer resumption until recording-stopped below.
+ if (this._pushToTalkAwaitingStop) {
+ this._pushToTalkResumeRequested = true;
+ } else if (!speechService.getStatus().isRecording) {
+ speechService.startRecording();
+ windowManager.broadcastToAllWindows('practice-mute-state', { muted: false });
+ logger.info('Practice hold-to-mute resumed microphone');
+ }
+ }
+ }
+ };
+
+ // Keep the shortcut out of chat and Settings, where Space must remain
+ // normal text input. The compact toolbar and answer panel are safe,
+ // non-editable practice surfaces.
+ let attachedWindows = 0;
+ for (const type of ['main', 'llmResponse']) {
+ const window = windowManager.getWindow(type);
+ if (!window || window.isDestroyed()) continue;
+ window.webContents.on('before-input-event', handleInput);
+ attachedWindows++;
+ }
+
+ logger.info('Practice hold-to-mute ready: hold Space in the focused toolbar or answer panel', { attachedWindows });
+ }
+
setupServiceEventHandlers() {
speechService.on("recording-started", () => {
+ this._speechRecordingStartedAt = Date.now();
windowManager.handleRecordingStarted();
});
speechService.on("recording-stopped", () => {
windowManager.handleRecordingStopped();
+ if (this._pushToTalkAwaitingStop) {
+ this._pushToTalkAwaitingStop = false;
+ if (this._pushToTalkResumeRequested) {
+ this._pushToTalkResumeRequested = false;
+ setTimeout(() => {
+ if (!speechService.getStatus().isRecording) {
+ speechService.startRecording();
+ windowManager.broadcastToAllWindows('practice-mute-state', { muted: false });
+ logger.info('Practice hold-to-mute resumed microphone after Azure stopped');
+ }
+ }, 0);
+ }
+ }
+ });
+
+ speechService.on("stop-requested", ({ provider, sessionDuration }) => {
+ this._speechStopRequestedAt = Date.now();
+ performanceMetrics.record('speech_capture_session', sessionDuration, { provider });
});
speechService.on("transcription", (text) => {
+ if (this._speechStopRequestedAt) {
+ performanceMetrics.record('speech_stt_finalize', Date.now() - this._speechStopRequestedAt, {
+ provider: speechService.provider, transcriptChars: String(text || '').length
+ });
+ this._speechStopRequestedAt = null;
+ }
this.handleTranscriptionFragment(text);
});
@@ -472,8 +613,32 @@ class ApplicationController {
}
});
- ipcMain.handle("get-speech-availability", () => {
+ ipcMain.handle("get-speech-availability", () => {
return speechService.isAvailable ? speechService.isAvailable() : false;
+ });
+
+ // Explicitly ask macOS from the packaged app's own identity before the
+ // renderer opens the microphone. Development runs remain separate under
+ // Electron, while the installed build is registered as OpenCluely.
+ ipcMain.handle("ensure-microphone-access", async () => {
+ if (process.platform !== "darwin" || !systemPreferences?.getMediaAccessStatus) {
+ return { granted: true, status: "not-applicable" };
+ }
+ const status = systemPreferences.getMediaAccessStatus("microphone");
+ if (status === "granted") return { granted: true, status };
+ if (status === "not-determined") {
+ const granted = await systemPreferences.askForMediaAccess("microphone");
+ return { granted, status: systemPreferences.getMediaAccessStatus("microphone") };
+ }
+ return { granted: false, status };
+ });
+
+ ipcMain.handle("get-skill-catalog", () => skillCatalog.map(({ id, name, category, knowledgeScope, responseStyle, displayFormat, latencyPreferences, languagePreferences }) => ({ id, name, category, knowledgeScope, responseStyle, displayFormat, latencyPreferences, languagePreferences })));
+
+ ipcMain.handle("get-performance-metrics", () => performanceMetrics.getSnapshot());
+ ipcMain.on("record-performance-metric", (_event, metric = {}) => {
+ if (typeof metric.name !== 'string' || !Number.isFinite(metric.durationMs)) return;
+ performanceMetrics.record(metric.name, metric.durationMs, metric.metadata || {});
});
ipcMain.handle("start-speech-recognition", () => {
@@ -487,9 +652,24 @@ class ApplicationController {
});
// Raw PCM audio captured by the renderer's Web Audio API (Windows Whisper path)
+ let audioChunkCount = 0;
+
ipcMain.on("audio-chunk", (_event, data) => {
if (data && data.buffer) {
- speechService.handleAudioChunkFromRenderer(Buffer.from(data.buffer));
+ audioChunkCount++;
+
+ // Audio frames are high-frequency IPC traffic; console writes are
+ // disproportionately expensive on an Intel Mac during recording.
+ if (audioChunkCount === 1 || audioChunkCount % 500 === 0) {
+ logger.debug('Renderer PCM received', {
+ chunkCount: audioChunkCount,
+ bytes: data.buffer.byteLength
+ });
+ }
+
+ speechService.handleAudioChunkFromRenderer(
+ Buffer.from(data.buffer)
+ );
}
});
@@ -731,6 +911,44 @@ class ApplicationController {
return this.getSettings();
});
+
+ ipcMain.handle("open-log-folder", async () => {
+ const { shell } = require("electron");
+ const logDirectory = appLogger.getLogDirectory();
+ const error = await shell.openPath(logDirectory);
+ return { success: !error, error: error || null, logDirectory };
+ });
+
+ ipcMain.handle("copy-diagnostic-logs", () => {
+ const { clipboard } = require("electron");
+ const logDirectory = appLogger.getLogDirectory();
+ const date = new Date().toISOString().slice(0, 10);
+ const paths = [
+ path.join(logDirectory, `application-${date}.log`),
+ path.join(logDirectory, `error-${date}.log`),
+ ];
+ const logs = paths.flatMap((logPath) => {
+ try {
+ const content = fs.readFileSync(logPath, "utf8");
+ return [`\n--- ${path.basename(logPath)} ---\n${content.slice(-16000)}`];
+ } catch (_) {
+ return [];
+ }
+ }).join("");
+ const safeLogs = appLogger.redactText(logs);
+ clipboard.writeText(safeLogs || `No log entries found in ${logDirectory}`);
+ return { success: true, logDirectory, copiedCharacters: safeLogs.length };
+ });
+
+ ipcMain.handle("open-screen-recording-preferences", async () => {
+ if (process.platform !== "darwin") {
+ return { success: false, error: "Screen Recording preferences are only available on macOS." };
+ }
+ const { shell } = require("electron");
+ const error = await shell.openExternal("x-apple.systempreferences:com.apple.preference.security?Privacy_ScreenCapture");
+ return { success: !error, error: error || null };
+ });
+
// First-run onboarding status — renderer can query to know whether
// to show the welcome banner / prompt for API-key entry.
ipcMain.handle("get-first-run-status", () => {
@@ -849,9 +1067,12 @@ class ApplicationController {
});
ipcMain.handle("update-active-skill", (event, skill) => {
- this.activeSkill = skill;
- windowManager.broadcastToAllWindows("skill-changed", { skill });
- return { success: true };
+ const normalizedSkill = normalizeProfileId(skill);
+ if (!isSupportedSkill(normalizedSkill)) return { success: false, error: "Unsupported skill" };
+ this.activeSkill = normalizedSkill;
+ sessionManager.setActiveSkill(normalizedSkill);
+ windowManager.broadcastToAllWindows("skill-changed", { skill: normalizedSkill });
+ return { success: true, skill: normalizedSkill };
});
ipcMain.handle("restart-app-for-stealth", () => {
@@ -924,8 +1145,14 @@ class ApplicationController {
// Handle update skill
ipcMain.on("update-skill", (event, skill) => {
- this.activeSkill = skill;
- windowManager.broadcastToAllWindows("skill-updated", { skill });
+ const normalizedSkill = normalizeProfileId(skill);
+ if (!isSupportedSkill(normalizedSkill)) {
+ logger.warn("Ignored unsupported skill change", { skill });
+ return;
+ }
+ this.activeSkill = normalizedSkill;
+ sessionManager.setActiveSkill(normalizedSkill);
+ windowManager.broadcastToAllWindows("skill-updated", { skill: normalizedSkill });
});
// Handle quit app (alternative method)
@@ -973,6 +1200,23 @@ class ApplicationController {
}
}
+ startInterviewMode() {
+ this.activeSkill = "amazon-dct";
+ sessionManager.setActiveSkill(this.activeSkill);
+ windowManager.broadcastToAllWindows("skill-updated", { skill: this.activeSkill });
+ windowManager.showChatWindow();
+
+ const status = speechService.getStatus();
+ if (!status.isRecording) {
+ this.toggleSpeechRecognition();
+ }
+
+ logger.info("Amazon DCT interview mode started", {
+ shortcut: "CommandOrControl+Shift+A",
+ speechWasRecording: status.isRecording,
+ });
+ }
+
clearSessionMemory() {
try {
sessionManager.clear();
@@ -1028,9 +1272,7 @@ class ApplicationController {
}
navigateSkill(direction) {
- const availableSkills = [
- "dsa",
- ];
+ const availableSkills = getNavigableProfileIds();
const currentIndex = availableSkills.indexOf(this.activeSkill);
if (currentIndex === -1) {
@@ -1072,11 +1314,13 @@ class ApplicationController {
}
const startTime = Date.now();
+ let captureCompleted = false;
try {
windowManager.showLLMLoading();
- const capture = await captureService.captureAndProcess();
+ const capture = await captureService.captureAndProcess();
+ captureCompleted = true;
if (!capture.imageBuffer || !capture.imageBuffer.length) {
windowManager.hideLLMResponse();
@@ -1087,8 +1331,7 @@ class ApplicationController {
// Use image directly with LLM and active skill; do not send chat messages here
const sessionHistory = sessionManager.getOptimizedHistory();
- const skillsRequiringProgrammingLanguage = ['dsa'];
- const needsProgrammingLanguage = skillsRequiringProgrammingLanguage.includes(this.activeSkill);
+ const needsProgrammingLanguage = require('./prompt-loader').promptLoader.requiresProgrammingLanguage(this.activeSkill);
this._responseSeq = (this._responseSeq || 0) + 1;
const messageId = `img-${Date.now()}-${this._responseSeq}`;
@@ -1129,12 +1372,19 @@ class ApplicationController {
});
} catch (error) {
logger.error("Screenshot OCR process failed", {
- error: error.message,
+ reason: error.message,
duration: Date.now() - startTime,
});
- windowManager.hideLLMResponse();
- this.broadcastOCRError(error.message);
+ const userFacingError = captureCompleted
+ ? llmService.getUserFacingError(error)
+ : error.message;
+ windowManager.showLLMResponse(userFacingError, {
+ skill: this.activeSkill,
+ usedFallback: true,
+ isError: true,
+ });
+ this.broadcastOCRError(userFacingError);
sessionManager.addConversationEvent({
role: 'system',
@@ -1153,8 +1403,7 @@ class ApplicationController {
sessionManager.addUserInput(text, 'llm_input');
// Check if current skill needs programming language context
- const skillsRequiringProgrammingLanguage = ['dsa'];
- const needsProgrammingLanguage = skillsRequiringProgrammingLanguage.includes(this.activeSkill);
+ const needsProgrammingLanguage = require('./prompt-loader').promptLoader.requiresProgrammingLanguage(this.activeSkill);
this._responseSeq = (this._responseSeq || 0) + 1;
const messageId = `chat-${Date.now()}-${this._responseSeq}`;
@@ -1206,10 +1455,15 @@ class ApplicationController {
skill: this.activeSkill,
});
- windowManager.hideLLMResponse();
+ const userFacingError = llmService.getUserFacingError(error);
+ windowManager.showLLMResponse(userFacingError, {
+ skill: this.activeSkill,
+ usedFallback: true,
+ isError: true,
+ });
sessionManager.addConversationEvent({
role: 'system',
- content: `LLM processing failed: ${error.message}`,
+ content: `LLM processing failed: ${userFacingError}`,
action: 'llm_error',
metadata: {
error: error.message,
@@ -1217,7 +1471,7 @@ class ApplicationController {
}
});
- this.broadcastLLMError(error.message);
+ this.broadcastLLMError(userFacingError);
}
}
@@ -1240,6 +1494,7 @@ class ApplicationController {
this._utteranceBuffer = this._utteranceBuffer
? `${this._utteranceBuffer} ${fragment}`
: fragment;
+ if (!this._utteranceStartedAt) this._utteranceStartedAt = Date.now();
if (this._utteranceTimer) {
clearTimeout(this._utteranceTimer);
@@ -1274,10 +1529,16 @@ class ApplicationController {
}
this._utteranceBuffer = "";
this._utteranceDispatchInFlight = true;
+ const utteranceStartedAt = this._utteranceStartedAt || Date.now();
+ this._utteranceStartedAt = null;
try {
+ performanceMetrics.record('speech_coalesce_wait', Date.now() - utteranceStartedAt, {
+ activeSkill: this.activeSkill,
+ characters: combined.length
+ });
const sessionHistory = sessionManager.getOptimizedHistory();
- await this.processTranscriptionWithLLM(combined, sessionHistory);
+ await this.processTranscriptionWithLLM(combined, sessionHistory, utteranceStartedAt);
} catch (error) {
logger.error("Failed to process transcription with LLM", {
error: error.message,
@@ -1292,7 +1553,7 @@ class ApplicationController {
}
}
- async processTranscriptionWithLLM(text, sessionHistory) {
+ async processTranscriptionWithLLM(text, sessionHistory, utteranceStartedAt = Date.now()) {
// Hoisted so the catch block can tie a fallback answer to the same UI
// bubble the streaming start event created; otherwise a total failure
// leaves an empty streamed bubble stranded next to the fallback message.
@@ -1322,8 +1583,7 @@ class ApplicationController {
});
// Check if current skill needs programming language context
- const skillsRequiringProgrammingLanguage = ['dsa'];
- const needsProgrammingLanguage = skillsRequiringProgrammingLanguage.includes(this.activeSkill);
+ const needsProgrammingLanguage = require('./prompt-loader').promptLoader.requiresProgrammingLanguage(this.activeSkill);
// Stream the answer progressively to the configured speech target.
// A unique messageId ties the start/chunk/final events to one bubble so
@@ -1350,6 +1610,13 @@ class ApplicationController {
}
);
llmResult.metadata = { ...llmResult.metadata, messageId };
+ const endToEndMs = Date.now() - utteranceStartedAt;
+ performanceMetrics.record('speech_to_answer', endToEndMs, {
+ activeSkill: this.activeSkill,
+ sttToFirstTokenMs: llmResult.metadata.firstTokenMs,
+ llmMs: llmResult.metadata.processingTime,
+ cacheHit: !!llmResult.metadata.cacheHit
+ });
// Add LLM response to session memory
sessionManager.addModelResponse(llmResult.response, {
@@ -1590,7 +1857,14 @@ class ApplicationController {
// distinguish "unset" from "stale value from a previous load".
return {
codingLanguage: this.codingLanguage || "cpp",
- activeSkill: this.activeSkill || "dsa",
+ activeSkill: this.activeSkill || "amazon-dct",
+ interviewCompany: this.interviewCompany,
+ responseMode: this.responseMode,
+ uiTheme: this.uiTheme,
+ compactMode: this.compactMode,
+ technologyContext: this.technologyContext,
+ candidateProfile: this.candidateProfile,
+ targetJobProfile: this.targetJobProfile,
appIcon: this.appIcon || "terminal",
selectedIcon: this.appIcon || "terminal",
windowGap: windowManager.windowGap,
@@ -1607,6 +1881,7 @@ class ApplicationController {
whisperResponseTarget: process.env.WHISPER_RESPONSE_TARGET || "both",
whisperSegmentMs: process.env.WHISPER_SEGMENT_MS || "4000",
geminiKey: process.env.GEMINI_API_KEY || "",
+ geminiModel: config.get('llm.gemini.model'),
azureConfigured: !!process.env.AZURE_SPEECH_KEY && !!process.env.AZURE_SPEECH_REGION,
speechAvailable: this.speechAvailable
@@ -1622,10 +1897,68 @@ class ApplicationController {
language: settings.codingLanguage,
});
}
- if (settings.activeSkill) {
- this.activeSkill = settings.activeSkill;
+ if (settings.activeSkill && isSupportedSkill(settings.activeSkill)) {
+ const normalizedSkill = normalizeProfileId(settings.activeSkill);
+ this.activeSkill = normalizedSkill;
+ sessionManager.setActiveSkill(normalizedSkill);
windowManager.broadcastToAllWindows("skill-updated", {
- skill: settings.activeSkill,
+ skill: normalizedSkill,
+ });
+ } else if (settings.activeSkill) {
+ logger.warn("Ignored unsupported active skill in settings", { skill: settings.activeSkill });
+ }
+ const validCompanies = ["general", "amazon", "google", "microsoft", "meta", "apple", "nvidia", "netflix"];
+ const validResponseModes = ["quick", "interview", "detailed", "star", "troubleshooting"];
+ const validThemes = ["dark", "light"];
+ let preferencesChanged = false;
+ let personalContextChanged = false;
+ if (validCompanies.includes(settings.interviewCompany)) {
+ this.interviewCompany = settings.interviewCompany;
+ preferencesChanged = true;
+ }
+ if (validResponseModes.includes(settings.responseMode)) {
+ this.responseMode = settings.responseMode;
+ preferencesChanged = true;
+ }
+ if (validThemes.includes(settings.uiTheme)) {
+ this.uiTheme = settings.uiTheme;
+ preferencesChanged = true;
+ }
+ if (typeof settings.compactMode === "boolean") {
+ this.compactMode = settings.compactMode;
+ preferencesChanged = true;
+ }
+ for (const category of ["database", "cloud", "containers", "infrastructure"]) {
+ const value = settings.technologyContext?.[category];
+ if (isSupportedTechnology(category, value)) {
+ this.technologyContext[category] = value;
+ preferencesChanged = true;
+ }
+ }
+ if (settings.candidateProfile !== undefined) {
+ const candidateProfile = normalizeProfileText(settings.candidateProfile);
+ personalContextChanged = candidateProfile !== this.candidateProfile;
+ this.candidateProfile = candidateProfile;
+ }
+ if (settings.targetJobProfile !== undefined) {
+ const targetJobProfile = normalizeProfileText(settings.targetJobProfile);
+ personalContextChanged = personalContextChanged || targetJobProfile !== this.targetJobProfile;
+ this.targetJobProfile = targetJobProfile;
+ }
+ if (preferencesChanged || personalContextChanged) {
+ llmService.setResponsePreferences({
+ company: this.interviewCompany,
+ responseMode: this.responseMode,
+ technologyContext: this.technologyContext,
+ candidateProfile: this.candidateProfile,
+ targetJobProfile: this.targetJobProfile
+ });
+ windowManager.broadcastToAllWindows("ui-preferences-changed", {
+ interviewCompany: this.interviewCompany,
+ responseMode: this.responseMode,
+ uiTheme: this.uiTheme,
+ compactMode: this.compactMode,
+ technologyContext: this.technologyContext
});
}
if (settings.appIcon) {
@@ -1678,6 +2011,42 @@ class ApplicationController {
if (settings.geminiKey !== undefined) {
envUpdates.GEMINI_API_KEY = settings.geminiKey;
}
+ if (settings.geminiModel !== undefined) {
+ envUpdates.GEMINI_MODEL = settings.geminiModel;
+ config.set('llm.gemini.model', settings.geminiModel);
+ }
+ if (preferencesChanged) {
+ envUpdates.INTERVIEW_COMPANY = this.interviewCompany;
+ envUpdates.RESPONSE_MODE = this.responseMode;
+ envUpdates.UI_THEME = this.uiTheme;
+ envUpdates.COMPACT_MODE = String(this.compactMode);
+ envUpdates.TECH_DATABASE = this.technologyContext.database;
+ envUpdates.TECH_CLOUD = this.technologyContext.cloud;
+ envUpdates.TECH_CONTAINERS = this.technologyContext.containers;
+ envUpdates.TECH_INFRASTRUCTURE = this.technologyContext.infrastructure;
+ }
+ if (settings.codingLanguage !== undefined) {
+ envUpdates.CODING_LANGUAGE = this.codingLanguage;
+ }
+ if (settings.activeSkill !== undefined) {
+ envUpdates.ACTIVE_SKILL = this.activeSkill;
+ }
+ if (settings.appIcon !== undefined || settings.selectedIcon !== undefined) {
+ envUpdates.APP_ICON = this.appIcon || "terminal";
+ }
+ if (settings.windowGap !== undefined) {
+ envUpdates.WINDOW_GAP = String(windowManager.windowGap);
+ }
+ if (settings.candidateProfile !== undefined) {
+ envUpdates.CANDIDATE_PROFILE_B64 = this.candidateProfile
+ ? Buffer.from(this.candidateProfile, "utf8").toString("base64")
+ : "";
+ }
+ if (settings.targetJobProfile !== undefined) {
+ envUpdates.TARGET_JOB_PROFILE_B64 = this.targetJobProfile
+ ? Buffer.from(this.targetJobProfile, "utf8").toString("base64")
+ : "";
+ }
// Capture the previous whisper command BEFORE persisting — persistEnvUpdates
// mutates process.env in place, so comparing afterwards would always read
@@ -1692,10 +2061,11 @@ class ApplicationController {
// connection button in the onboarding wizard fails with
// "Service not initialized" because the client was first created
// at app startup, before any key was set.
- if (settings.geminiKey !== undefined && envUpdates.GEMINI_API_KEY !== undefined) {
+ if ((settings.geminiKey !== undefined && envUpdates.GEMINI_API_KEY !== undefined) ||
+ settings.geminiModel !== undefined) {
try {
llmService.initializeClient();
- logger.info("LLM service reinitialized after Gemini key update");
+ logger.info("LLM service reinitialized after Gemini configuration update");
} catch (e) {
logger.warn("Failed to reinitialize LLM service after Gemini key update", {
error: e.message
@@ -1740,8 +2110,11 @@ class ApplicationController {
}
logger.info("Settings saved successfully", {
- ...settings,
- persistedEnvKeys: persistedKeys
+ persistedEnvKeys: persistedKeys,
+ preferencesChanged,
+ personalContextChanged,
+ candidateProfileLength: this.candidateProfile.length,
+ targetJobProfileLength: this.targetJobProfile.length
});
return { success: true, persistedEnvKeys: persistedKeys };
} catch (error) {
diff --git a/onboarding.html b/onboarding.html
index 7e2db50d..b78992dc 100644
--- a/onboarding.html
+++ b/onboarding.html
@@ -957,9 +957,9 @@ Enjoying OpenCluely?
-