First-run demo walkthrough

docs/E2E_WALKTHROUGH.md

@@ -19,13 +19,15 @@ Linux AppImage (v2.0.4). Each section maps to one phase of the app workflow.
 7. [Search & Knowledge OS](#7-search--knowledge-os)
 8. [Settings — Full Reference](#8-settings--full-reference)
 9. [Videos](#9-videos)
+10. [Video Transcripts (VoiceOver)](#video-transcripts-voiceover)
 
 ---
 
 ## 1. First Launch & Model Setup
 
-On first launch, StratoSort checks for AI models in `~/.config/stratosort-core/models/`. If
-required models are missing, a setup wizard guides you through downloading them.
+On first launch, StratoSort checks for AI models in `~/.config/StratoSort Core/models/` (via
+`app.getPath('userData')`). If required models are missing, a setup wizard guides you through
+downloading them.
 
 ### Model Selection
 
@@ -557,6 +559,21 @@ interactions:
 | `07_prod_organize_and_knowledge_os.mp4` | ~3 min | Production AppImage: Organize phase, Search widget, Knowledge OS Discover tab searches |
 | `08_knowledge_os_all_tabs_complete.mp4` | ~8 min | **All Knowledge OS tabs**: Discover search, Understand (AI chat with RAG), Relate (Knowledge Graph with clusters, insights, legend) |
 
+### Video Transcripts (VoiceOver)
+
+Transcripts for accessibility and audio VoiceOver are in `docs/e2e-transcripts/`. Each transcript
+describes the on-screen content in narrative form for recording:
+
+| Transcript | Video |
+|:-----------|:------|
+| `01_welcome_and_setup_walkthrough.md` | Welcome, How it works modal, Setup, Add Folder, Discover |
+| `02_discover_phase_walkthrough.md` | Naming Strategy, Knowledge OS, file selection, analysis start |
+| `03_discover_analysis_and_model_setup.md` | Model download wizard, progress bars, Scan Folder |
+| `04_settings_search_and_navigation.md` | Search widget, Settings panel, Knowledge OS |
+| `05_settings_deep_dive_and_scan_folder.md` | All 6 Settings sections, Scan Folder demo |
+| `06_organize_and_knowledge_os_demo.md` | Organize phase, AI suggestions, Knowledge OS search |
+| `08_knowledge_os_all_tabs_complete.md` | Discover, Understand, Relate tabs |
+
 ---
 
 ## Linux-Specific Notes
@@ -573,8 +590,10 @@ chmod +x StratoSortCore-2.0.4-linux-x86_64.AppImage
 
 ### Models Directory
 
-Models are stored in `~/.config/stratosort-core/models/`. The app creates this directory
-automatically and downloads models on first launch.
+Models are stored in `~/.config/StratoSort Core/models/` (the `userData` path). The app creates
+this directory automatically and downloads models on first launch. Note: The legacy path
+`~/.config/stratosort-core/models/` is used by the postinstall script; the running app uses
+the `StratoSort Core` path.
 
 ### Settings Location
 

docs/e2e-transcripts/01_welcome_and_setup_walkthrough.md

@@ -0,0 +1,25 @@
+# Transcript: 01 Welcome and Setup Walkthrough
+
+**Video:** `e2e-videos/01_welcome_and_setup_walkthrough.mp4`  
+**Duration:** ~2 minutes  
+**Use:** VoiceOver narration for accessibility
+
+---
+
+## Transcript
+
+The StratoSort Core window opens in full screen. The Welcome screen displays the StratoSort logo at the top with a green connection indicator showing the AI engine is ready.
+
+Below the logo, four phase tabs are visible: Welcome, Setup, Discover, Organize, and Complete. The Welcome tab is selected. A search button and settings gear icon sit in the top-right corner.
+
+The main Welcome area shows three action buttons: "Organize files now," "AI and model settings," and "Configure smart folders." A link reads "How does StratoSort work?"
+
+The user clicks "How does StratoSort work?" A modal dialog appears with the title "How does StratoSort work?" The modal explains three steps: Discover — drop folders, run system scans, or watch Downloads automatically; Analyze — local AI reads file contents, context, and prior choices; Organize — approve suggestions, rename intelligently, undo instantly. The user closes the modal.
+
+The user clicks "Configure smart folders" and navigates to the Setup phase. The Setup screen shows a list of Smart Folders. A default "Uncategorized" folder appears with its path. An "Add Folder" button is visible.
+
+The user clicks "Add Folder." The Add Smart Folder dialog opens with fields for Folder Name, Target Path, and Description. A "Generate with AI" button is available for the description. The user enters a folder name and path, then confirms.
+
+The Setup phase now shows multiple Smart Folders. A "Continue to Discovery" button appears at the bottom. The user clicks it and navigates to the Discover phase.
+
+The Discover phase displays the file import area with options to select files or scan a folder. The walkthrough ends on the Discover screen.

docs/e2e-transcripts/02_discover_phase_walkthrough.md

@@ -0,0 +1,23 @@
+# Transcript: 02 Discover Phase Walkthrough
+
+**Video:** `e2e-videos/02_discover_phase_walkthrough.mp4`  
+**Duration:** ~3 minutes  
+**Use:** VoiceOver narration for accessibility
+
+---
+
+## Transcript
+
+The StratoSort app is on the Discover phase. The navigation bar shows Welcome, Setup, Discover, Organize, and Complete. Discover is selected.
+
+In the upper-right corner, two buttons are visible: "Naming Strategy" and "Knowledge OS." The main area shows options to add files: "Select Files" and "Scan Folder."
+
+The user clicks "Naming Strategy." A modal opens titled "Naming Strategy." The modal shows settings for file naming: Convention with options like subject-date, date-subject, and subject-only; Date Format with YYYY-MM-DD, MM-DD-YYYY, and DD-MM-YYYY; Case with kebab-case, snake_case, camelCase, and Title Case; and Separator with dash, dot, underscore, and none. A live preview shows the resulting filename format. The user closes the modal.
+
+The user clicks "Knowledge OS." The Knowledge OS panel slides in from the right. Three tabs appear: Discover, Understand, and Relate. The Discover tab is selected. A search bar and status message indicate the number of folders and files indexed. The panel explains that Knowledge OS enables semantic search across analyzed files. The user closes the panel.
+
+The user clicks "Select Files." A file picker dialog opens. The user navigates to a directory and selects multiple files. The selection is confirmed.
+
+Back on the Discover screen, the selected files appear in a queue. A progress indicator shows "Analyzing" with a file counter. A "Stop Analysis" button is visible. A toast notification appears: "Added N new files for analysis" and "Starting AI analysis of N files."
+
+The analysis progress bar advances. The walkthrough ends with analysis in progress.

docs/e2e-transcripts/03_discover_analysis_and_model_setup.md

@@ -0,0 +1,23 @@
+# Transcript: 03 Discover Analysis and Model Setup
+
+**Video:** `e2e-videos/03_discover_analysis_and_model_setup.mp4`  
+**Duration:** ~3 minutes  
+**Use:** VoiceOver narration for accessibility
+
+---
+
+## Transcript
+
+The StratoSort Model Setup Wizard is displayed. This screen appears on first launch when required AI models are not yet installed.
+
+The wizard shows a table of models: Embedding Model, Text Analysis Model, and Vision Model. Each row displays the model name, purpose, installation status — Installed or Not installed — and download size. Checkboxes allow selecting which models to download.
+
+Three action buttons appear at the bottom: "Download Models," "Refresh," and "Continue with limited AI."
+
+The user clicks "Download Models." Progress bars appear for each selected model. Each bar shows the model name, download speed in megabytes per second, and a percentage complete. The embedding model and text model progress bars fill as downloads proceed.
+
+The user can also click "Continue with limited AI" to skip setup and enter the app immediately. The app will download models in the background while the user explores.
+
+The wizard is dismissed. The app transitions to the Discover phase. The user clicks "Scan Folder." A folder picker opens. The user selects a directory. StratoSort discovers all supported files within that folder and adds them to the analysis queue.
+
+The Discover screen shows the file queue with an "Analyzing" progress indicator. The walkthrough demonstrates that model setup and file discovery work together seamlessly.

docs/e2e-transcripts/04_settings_search_and_navigation.md

@@ -0,0 +1,19 @@
+# Transcript: 04 Settings Search and Navigation
+
+**Video:** `e2e-videos/04_settings_search_and_navigation.mp4`  
+**Duration:** ~3 minutes  
+**Use:** VoiceOver narration for accessibility
+
+---
+
+## Transcript
+
+The StratoSort app is open. The user clicks the search button in the navigation bar. A floating Search widget appears. The widget explains Knowledge OS capabilities: semantic search, natural language queries, and document relationships. An "Open Knowledge OS" button is prominent. A keyboard shortcut is shown: Ctrl+K to open search from anywhere.
+
+The user closes the widget and clicks the settings gear icon. The Settings panel opens as a slide-out panel from the right. Six collapsible sections are visible: AI Configuration, Performance, Default Locations, Application, Analysis History, and Diagnostics.
+
+The user expands the AI Configuration section. It shows the Local AI Engine status — Ready with CPU or GPU — and model selection for Text, Vision, and Embedding models. GPU Acceleration toggle and model management options are visible.
+
+The user scrolls through the Settings panel. Each section can be expanded to reveal detailed options. The Performance section includes Auto-Organize, Background Mode, and Processing Limits. Default Locations covers Smart Folder base path and naming defaults. Application includes Launch on Startup and Software Updates. Notifications, Backup and Restore, Analysis History, and Diagnostics complete the panel.
+
+The user closes Settings and clicks the Search button again. The Knowledge OS full interface opens. The Discover tab shows the search bar and indexed file count. The user can type natural language queries to find files. The walkthrough ends with the Knowledge OS interface open.

docs/e2e-transcripts/05_settings_deep_dive_and_scan_folder.md

@@ -0,0 +1,25 @@
+# Transcript: 05 Settings Deep Dive and Scan Folder
+
+**Video:** `e2e-videos/05_settings_deep_dive_and_scan_folder.mp4`  
+**Duration:** ~12 minutes  
+**Use:** VoiceOver narration for accessibility
+
+---
+
+## Transcript
+
+The StratoSort Settings panel is open with all six sections expanded. This is a comprehensive tour of every configuration option.
+
+**AI Configuration.** The Local AI Engine shows status and GPU toggle. Default AI Models lists Text Model, Vision Model, and Embedding Model with dropdown selectors. Model Management allows downloading additional GGUF models. Embedding Behavior includes Embedding Scope, Embedding Timing, Default Embedding Policy, and Auto-generate Chunk Embeddings. A "Rebuild All Embeddings" button is available.
+
+**Performance.** Auto-Organize Downloads toggle. Smart Folder Routing with options: Auto, LLM-only, Embedding-first, and Hybrid. Background Mode toggle. Processing Limits: Concurrent Analysis, max file sizes for general files, images, and documents. Graph Retrieval: Enable Graph Expansion, Graph Expansion Weight slider, Graph Neighbors Limit, and Contextual Chunk Expansion.
+
+**Default Locations.** Default Smart Folder Location with Browse button. File Naming Defaults mirroring the Naming Strategy options.
+
+**Application.** Launch on Startup. Software Updates button. Notifications: Enable Notifications, Display Mode — App and system tray, App only, or System tray only. Notification Events: Auto-analyzed files and Low confidence files. Settings Backup and Restore: Create Backup, Export to File, Import from File, and Available Backups list.
+
+**Analysis History.** View Analysis History button to open past analysis results.
+
+**Diagnostics.** Open Folder for logs. Export Logs for support tickets. Backend API Test to run connectivity checks.
+
+The user closes Settings and navigates to Discover. The "Scan Folder" button is clicked. A folder picker opens. The user selects a directory. StratoSort scans the folder and discovers all supported files. The files appear in the queue. The Scan Folder feature is demonstrated end-to-end.

docs/e2e-transcripts/06_organize_and_knowledge_os_demo.md

@@ -0,0 +1,25 @@
+# Transcript: 06 Organize and Knowledge OS Demo
+
+**Video:** `e2e-videos/06_organize_and_knowledge_os_demo.mp4`  
+**Duration:** ~4 minutes  
+**Use:** VoiceOver narration for accessibility
+
+---
+
+## Transcript
+
+AI analysis has completed. The Discover phase shows a green status: "Analysis complete" with the number of files ready. A toast notification confirms "Analysis complete! N files ready."
+
+The user navigates to the Organize phase. The Organize screen displays a grid of file cards. Each card shows the original filename, a "Ready" badge, the AI-suggested name, a Category dropdown, and a confidence percentage in green. A "Details" link opens the full AI analysis for each file.
+
+Example suggestions are visible: an invoice file suggested as "consulting-invoice" with 100% confidence; meeting notes suggested as "product-plan-session-notes" with 95% confidence; an onboarding checklist with 100% confidence. The Category dropdown lets the user change the destination folder for each file.
+
+Batch operations are available: "Select All," "Approve Selected," "Bulk Edit," and "Deselect All." The user can approve suggestions individually or in bulk.
+
+The user clicks the Search button to open Knowledge OS. The Knowledge OS panel shows the Discover tab with indexed files. The status bar reads "N folders, N files indexed."
+
+The user types "invoice" in the search bar. Search results appear. A file matching "invoice" is highlighted with tags: consulting, invoice, business, and confidence score. A file preview shows content and path. "View in Graph" and "Ask AI" buttons are available.
+
+The user clears the search and types "meeting notes about product planning." Natural language search returns relevant files. A meeting notes file appears with 95% confidence, tags like "product planning" and "meeting notes," and a full content preview. The "Open File" button is visible.
+
+The demo shows that AI analysis, Organize suggestions, and Knowledge OS semantic search work together in the production AppImage.

docs/e2e-transcripts/08_knowledge_os_all_tabs_complete.md

@@ -0,0 +1,29 @@
+# Transcript: 08 Knowledge OS All Tabs Complete
+
+**Video:** `e2e-videos/08_knowledge_os_all_tabs_complete.mp4`  
+**Duration:** ~8 minutes  
+**Use:** VoiceOver narration for accessibility
+
+---
+
+## Transcript
+
+The Knowledge OS panel is open with all three tabs demonstrated.
+
+**Discover Tab.** The default tab. A search bar at the top with placeholder text for natural language queries. The results list shows files ranked by semantic relevance with confidence scores. Clicking a result displays the file preview on the right: content, tags, and action buttons including "View in Graph" and "Ask AI." The status bar shows folder count and indexed file count.
+
+**Understand Tab.** The user clicks the Understand tab. This is the AI conversational chat interface. A "New Chat" button and search-for-chats field are visible. The chat input reads "Ask a question about your documents." The user types a question such as "What is this invoice about?" and sends it.
+
+The AI responds with "Searching documents..." then "Found N relevant sources." The response includes an answer drawn from the indexed documents. Source citations or file references may appear. This is RAG — Retrieval-Augmented Generation — chat over your local files.
+
+**Relate Tab.** The user clicks the Relate tab. The Knowledge Graph visualization appears. The left panel shows graph controls: current graph stats — Nodes and Links — Insights panel, Add to Graph search, and Explore, Actions, and Advanced sections. A three-step tutorial may be visible for first-time users.
+
+The center canvas displays an interactive node-link diagram. Clusters of related files appear as grouped nodes. A "Clusters On/Off" toggle controls cluster visibility. Zoom and pan controls are available. Double-clicking a cluster expands it to show individual file nodes with relationship edges.
+
+The right panel shows the legend: Node Types — Cluster in orange, File in blue, Query in purple; Connection Logic — Shared Tags, Same Category, Content Match, Vector Similarity; File Categories — Documents, Images, Audio, Spreadsheets, Code, Videos; Cluster confidence indicators.
+
+Clicking a cluster reveals details: file count, confidence level, "WHY THIS CLUSTER" with common tags, and "WHY CONNECTED" with per-file connection reasons. "Show only cluster" and "Show neighbors" buttons refine the view.
+
+The Insights panel displays organizational metrics: topic clusters count, bridge documents, near-duplicates, scattered files, and Organizational Health score from A to F with percentage.
+
+The walkthrough concludes with the full Knowledge Graph and legend visible, demonstrating all three Knowledge OS tabs: Discover for search, Understand for AI chat, and Relate for the graph.

docs/e2e-transcripts/README.md

@@ -0,0 +1,29 @@
+# E2E Video Transcripts
+
+Narrative transcripts for StratoSort Core walkthrough videos. Use these for:
+
+- **VoiceOver recording** — Read aloud for accessibility
+- **Closed captions** — Adapt for subtitles
+- **Script reference** — When re-recording or editing videos
+
+## Format
+
+Each transcript is a markdown file matching the video filename (e.g. `01_welcome_and_setup_walkthrough.md` for `01_welcome_and_setup_walkthrough.mp4`). The content describes on-screen actions and UI elements in sequential order, written for spoken delivery.
+
+## Videos Covered
+
+| Transcript | Video |
+|:-----------|:------|
+| 01_welcome_and_setup_walkthrough | Welcome screen, How it works modal, Setup phase, Add Folder, Discover |
+| 02_discover_phase_walkthrough | Naming Strategy, Knowledge OS panel, file selection, analysis start |
+| 03_discover_analysis_and_model_setup | Model download wizard, progress bars, Continue with limited AI, Scan Folder |
+| 04_settings_search_and_navigation | Search widget, Settings panel (6 sections), Knowledge OS interface |
+| 05_settings_deep_dive_and_scan_folder | All Settings sections expanded, Scan Folder demonstration |
+| 06_organize_and_knowledge_os_demo | Organize phase with AI suggestions, Knowledge OS semantic search |
+| 08_knowledge_os_all_tabs_complete | Discover, Understand (AI chat), Relate (Knowledge Graph) tabs |
+
+## Recording Tips
+
+- Pause briefly between sections for natural pacing
+- Emphasize button names and key actions
+- Adjust speed to match on-screen transitions