docs: update quick start guides and core concepts for clarity and accuracy

docs/0-START-HERE/index.md

@@ -5,20 +5,20 @@
 ## Choose Your Path
 
 ### 🚀 I want to use OpenAI (Fastest)
-**5 minutes to running.** GPT-4, simple setup, powerful results.
+**5 minutes to running.** GPT, simple setup, powerful results.
 
 → [OpenAI Quick Start](quick-start-openai.md)
 
 ---
 
-### ☁️ I want to use other cloud AI (Anthropic, Google, Groq, etc.)
+### ☁️ I want to use other cloud AI (Anthropic, Google, OpenRouter, etc.)
 **5 minutes to running.** Choose from 15+ AI providers.
 
 → [Cloud Providers Quick Start](quick-start-cloud.md)
 
 ---
 
-### 🏠 I want to run locally (Ollama, completely private)
+### 🏠 I want to run locally (Ollama or LMStudio, completely private)
 **5 minutes to running.** Keep everything private, on your machine. No costs.
 
 → [Local Quick Start](quick-start-local.md)
@@ -41,21 +41,13 @@
 | **Privacy** | Self-hosted, your control | Cloud, Google's servers |
 | **AI Choice** | 15+ providers | Google's models only |
 | **Podcast Speakers** | 1-4 customizable | 2 only |
-| **Cost** | Pay what you use | Free (but your data) |
+| **Cost** | Completely free | Free (but your data) |
-| **Offline** | Yes (with Ollama) | No |
+| **Offline** | Yes  | No |
 
 ## Prerequisites
 
 - **Docker**: All paths use Docker (free)
 - **AI Provider**: Either a cloud API key OR use free local models (Ollama)
-- **Browser**: Modern browser (Chrome, Firefox, Safari, Edge)
-
-## System Requirements
-
-- **RAM**: 4GB minimum (8GB recommended)
-- **Storage**: 2GB for app + space for documents
-- **CPU**: Any modern processor
-- **Network**: Internet for cloud AI (optional for local)
 
 ---
 

docs/0-START-HERE/quick-start-cloud.md

@@ -9,6 +9,7 @@ Get Open Notebook running with **Anthropic, Google, Groq, or other cloud provide
    - Already have it? Skip to step 2
 
 2. **API Key** from your chosen provider:
+   - **OpenRouter** (100+ models, one key): https://openrouter.ai/keys
    - **Anthropic (Claude)**: https://console.anthropic.com/
    - **Google (Gemini)**: https://aistudio.google.com/
    - **Groq** (fast, free tier): https://console.groq.com/
@@ -29,15 +30,19 @@ services:
     ports:
       - "8000:8000"
 
-  api:
+  open_notebook:
     image: lfnovo/open_notebook:v1-latest
     ports:
-      - "5055:5055"
+      - "8502:8502"  # Web UI
+      - "5055:5055"  # API
     environment:
       # Choose ONE provider (uncomment your choice):
 
+      # OpenRouter - 100+ models with one API key
+      - OPENROUTER_API_KEY=sk-or-...
+
       # Anthropic (Claude) - Excellent reasoning
-      - ANTHROPIC_API_KEY=sk-ant-...
+      # - ANTHROPIC_API_KEY=sk-ant-...
 
       # Google (Gemini) - Large context, cost-effective
       # - GOOGLE_API_KEY=...
@@ -54,21 +59,12 @@ services:
       - SURREAL_PASSWORD=password
       - SURREAL_NAMESPACE=open_notebook
       - SURREAL_DATABASE=production
+    volumes:
+      - ./notebook_data:/app/data
     depends_on:
       - surrealdb
-    volumes:
-      - ./data:/app/data
     restart: always
 
-  frontend:
-    image: lfnovo/open_notebook-frontend:v1-latest
-    ports:
-      - "3000:3000"
-    environment:
-      - NEXT_PUBLIC_API_URL=http://localhost:5055
-    depends_on:
-      - api
-    restart: always
 ```
 
 **Edit the file:**
@@ -93,7 +89,7 @@ Wait 15-20 seconds for services to start.
 
 Open your browser:
 ```
-http://localhost:3000
+http://localhost:8502
 ```
 
 You should see the Open Notebook interface!
@@ -108,6 +104,7 @@ You should see the Open Notebook interface!
 
 | Provider | Recommended Model | Notes |
 |----------|-------------------|-------|
+| **OpenRouter** | `anthropic/claude-3.5-sonnet` | Access 100+ models |
 | **Anthropic** | `claude-3-5-sonnet-latest` | Best reasoning |
 | **Google** | `gemini-2.0-flash` | Large context, fast |
 | **Groq** | `llama-3.3-70b-versatile` | Ultra-fast |
@@ -138,7 +135,7 @@ You should see the Open Notebook interface!
 ## Verification Checklist
 
 - [ ] Docker is running
-- [ ] You can access `http://localhost:3000`
+- [ ] You can access `http://localhost:8502`
 - [ ] Models are configured for your provider
 - [ ] You created a notebook
 - [ ] Chat works
@@ -151,6 +148,7 @@ You should see the Open Notebook interface!
 
 | Provider | Speed | Quality | Context | Cost |
 |----------|-------|---------|---------|------|
+| **OpenRouter** | Varies | Varies | Varies | Varies (100+ models) |
 | **Anthropic** | Medium | Excellent | 200K | $$$ |
 | **Google** | Fast | Very Good | 1M+ | $$ |
 | **Groq** | Ultra-fast | Good | 128K | $ (free tier) |
@@ -165,6 +163,7 @@ You can enable multiple providers simultaneously:
 
 ```yaml
 environment:
+  - OPENROUTER_API_KEY=sk-or-...
   - ANTHROPIC_API_KEY=sk-ant-...
   - GOOGLE_API_KEY=...
   - GROQ_API_KEY=gsk_...

docs/0-START-HERE/quick-start-local.md

@@ -8,9 +8,9 @@ Get Open Notebook running with **100% local AI** using Ollama. No cloud API keys
    - [Download here](https://www.docker.com/products/docker-desktop/)
    - Already have it? Skip to step 2
 
-2. **Ollama** installed (for local LLM)
+2. **Local LLM** - Choose one:
-   - [Download here](https://ollama.ai/)
+   - **Ollama** (recommended): [Download here](https://ollama.ai/)
-   - Or use Docker image (easier): `ollama/ollama`
+   - **LM Studio** (GUI alternative): [Download here](https://lmstudio.ai)
 
 ## Step 1: Choose Your Setup (1 min)
 
@@ -237,10 +237,31 @@ docker exec open_notebook-ollama-1 ollama pull neural-chat
 
 ---
 
+## Alternative: Using LM Studio Instead of Ollama
+
+**Prefer a GUI?** LM Studio is easier for non-technical users:
+
+1. Download LM Studio: https://lmstudio.ai
+2. Open the app, download a model from the library
+3. Go to "Local Server" tab, start server (port 1234)
+4. Update your docker-compose.yml:
+   ```yaml
+   environment:
+     - OPENAI_COMPATIBLE_BASE_URL=http://host.docker.internal:1234/v1
+     - OPENAI_COMPATIBLE_API_KEY=not-needed
+   ```
+5. Configure in Settings → Models → Select your LM Studio model
+
+**Note**: LM Studio runs outside Docker, use `host.docker.internal` to connect.
+
+---
+
 ## Going Further
 
 - **Switch models**: Change in Settings → Models anytime
-- **Add more models**: Run `ollama pull <model>` and they'll appear in Settings
+- **Add more models**:
+  - Ollama: Run `ollama pull <model>`
+  - LM Studio: Download from the app library
 - **Deploy to server**: Same docker-compose.yml works anywhere
 - **Use cloud hybrid**: Keep some local models, add OpenAI/Anthropic for complex tasks
 

docs/0-START-HERE/quick-start-openai.md

@@ -27,10 +27,11 @@ services:
     ports:
       - "8000:8000"
 
-  api:
+  open_notebook:
     image: lfnovo/open_notebook:v1-latest
     ports:
-      - "5055:5055"
+      - "8502:8502"  # Web UI
+      - "5055:5055"  # API
     environment:
       # Your OpenAI key
       - OPENAI_API_KEY=sk-...
@@ -41,20 +42,10 @@ services:
       - SURREAL_PASSWORD=password
       - SURREAL_NAMESPACE=open_notebook
       - SURREAL_DATABASE=production
+    volumes:
+      - ./notebook_data:/app/data
     depends_on:
       - surrealdb
-    volumes:
-      - ./data:/app/data
-    restart: always
-
-  frontend:
-    image: lfnovo/open_notebook-frontend:v1-latest
-    ports:
-      - "3000:3000"
-    environment:
-      - NEXT_PUBLIC_API_URL=http://localhost:5055
-    depends_on:
-      - api
     restart: always
 ```
 
@@ -79,7 +70,7 @@ Wait 15-20 seconds for services to start.
 
 Open your browser:
 ```
-http://localhost:3000
+http://localhost:8502
 ```
 
 You should see the Open Notebook interface!
@@ -116,7 +107,7 @@ You should see the Open Notebook interface!
 ## Verification Checklist
 
 - [ ] Docker is running
-- [ ] You can access `http://localhost:3000`
+- [ ] You can access `http://localhost:8502`
 - [ ] You created a notebook
 - [ ] You added a source
 - [ ] Chat works
@@ -135,15 +126,15 @@ In your notebook, go to **Settings** → **Models** to choose:
 
 ## Troubleshooting
 
-### "Port 3000 already in use"
+### "Port 8502 already in use"
 
 Change the port in docker-compose.yml:
 ```yaml
 ports:
-  - "3001:3000"  # Use 3001 instead
+  - "8503:8502"  # Use 8503 instead
 ```
 
-Then access at `http://localhost:3001`
+Then access at `http://localhost:8503`
 
 ### "API key not working"
 

docs/1-INSTALLATION/docker-compose.md

@@ -42,10 +42,11 @@ services:
     volumes:
       - surreal_data:/mydata
 
-  api:
+  open_notebook:
     image: lfnovo/open_notebook:v1-latest
     ports:
-      - "5055:5055"
+      - "8502:8502"  # Web UI
+      - "5055:5055"  # API
     environment:
       # AI Provider (choose ONE)
       - OPENAI_API_KEY=sk-...  # Your OpenAI key
@@ -58,23 +59,10 @@ services:
       - SURREAL_PASSWORD=password
       - SURREAL_NAMESPACE=open_notebook
       - SURREAL_DATABASE=production
-
+    volumes:
-      # API Configuration
+      - ./notebook_data:/app/data
-      - API_URL=http://localhost:5055
     depends_on:
       - surrealdb
-    volumes:
-      - ./data:/app/data
-    restart: always
-
-  frontend:
-    image: lfnovo/open_notebook-frontend:v1-latest
-    ports:
-      - "3000:3000"
-    environment:
-      - NEXT_PUBLIC_API_URL=http://localhost:5055
-    depends_on:
-      - api
     restart: always
 
 volumes:
@@ -99,8 +87,7 @@ docker compose up -d
 Wait 15-20 seconds for all services to start:
 ```
 ✅ surrealdb running on :8000
-✅ api running on :5055
+✅ open_notebook running on :8502 (UI) and :5055 (API)
-✅ frontend running on :3000
 ```
 
 Check status:
@@ -121,7 +108,7 @@ curl http://localhost:5055/health
 **Frontend Access:**
 Open browser to:
 ```
-http://localhost:3000
+http://localhost:8502
 ```
 
 You should see the Open Notebook interface!
@@ -265,14 +252,15 @@ docker compose logs api
 
 ### Port Already in Use
 
-If you get "Port 3000 already in use", change the port:
+If you get "Port 8502 already in use", change the port:
 
 ```yaml
 ports:
-  - "3001:3000"  # Use 3001 instead
+  - "8503:8502"  # Use 8503 instead
+  - "5055:5055"  # Keep API port same
 ```
 
-Then access at `http://localhost:3001`
+Then access at `http://localhost:8503`
 
 ---
 

docs/1-INSTALLATION/index.md

@@ -110,7 +110,7 @@ Before installing, you'll need:
 1. Have Python 3.11+, Node.js 18+, Git installed
 2. Follow [From Source](from-source.md)
 3. Run `make start-all`
-4. Access at `http://localhost:3000` (frontend) or `http://localhost:5055` (API)
+4. Access at `http://localhost:8502` (frontend) or `http://localhost:5055` (API)
 
 ---
 

docs/2-CORE-CONCEPTS/ai-context-rag.md

@@ -1,6 +1,6 @@
 # AI Context & RAG - How Open Notebook Uses Your Research
 
-The core innovation in Open Notebook is how it makes AI models aware of your private research without uploading everything to the cloud. This section explains the "why" and "how" of that system.
+Open Notebook uses different approaches to make AI models aware of your research depending on the feature. This section explains **RAG** (used in Ask) and **full-content context** (used in Chat).
 
 ---
 
@@ -23,10 +23,17 @@ The core innovation in Open Notebook is how it makes AI models aware of your pri
 - Pro: Private, free
 - Con: AI doesn't know anything about your specific topic
 
-### Open Notebook's Solution: RAG
+### Open Notebook's Dual Approach
-**RAG** = Retrieval-Augmented Generation
 
-The insight: *Instead of changing the model, change what information you feed it.*
+**For Chat**: Sends the entire selected content to the LLM
+- Simple and transparent: You select sources, they're sent in full
+- Maximum context: AI sees everything you choose
+- You control which sources are included
+
+**For Ask (RAG)**: Retrieval-Augmented Generation
+- RAG = Retrieval-Augmented Generation
+- The insight: *Search your content, find relevant pieces, send only those*
+- Automatic: AI decides what's relevant based on your question
 
 ---
 
@@ -260,45 +267,83 @@ Result: AI doesn't get distracted; gives better answer
 
 ## The Difference: Chat vs. Ask
 
-Both use RAG, but differently.
+**IMPORTANT**: These use completely different approaches!
 
-### Chat: Manual Context Control
+### Chat: Full-Content Context (NO RAG)
+
+**How it works:**
 ```
 YOU:
-  1. Choose which sources to include
+  1. Select which sources to include in context
   2. Set context level (full/summary/excluded)
   3. Ask question
 
 SYSTEM:
-  - Uses ONLY the sources you selected
+  - Takes ALL selected sources (respecting context levels)
-  - Respects your context levels
+  - Sends the ENTIRE content to the LLM at once
-  - Answers based on what you chose
+  - NO search, NO retrieval, NO chunking
+  - AI sees everything you selected
 
-YOU:
+AI:
-  4. Ask follow-up (context stays the same)
+  - Responds based on the full content you provided
-  5. Or change context for next question
+  - Can reference any part of selected sources
+  - Conversational: context stays for follow-ups
 ```
 
-**Use this when**: You know which sources matter for THIS conversation.
+**Use this when**:
+- You know which sources are relevant
+- You want conversational back-and-forth
+- You want AI to see the complete context
+- You're doing close reading or analysis
 
-### Ask: Automatic Search
+**Advantages:**
+- Simple and transparent
+- AI sees everything (no missed content)
+- Conversational flow
+
+**Limitations:**
+- Limited by LLM context window
+- You must manually select relevant sources
+- Sends more tokens (higher cost with many sources)
+
+---
+
+### Ask: RAG - Automatic Retrieval
+
+**How it works:**
 ```
 YOU:
   Ask one complex question
 
 SYSTEM:
-  1. Analyzes your question (using smart model)
+  1. Analyzes your question
-  2. Breaks it into searchable parts
+  2. Searches across ALL your sources automatically
-  3. Automatically searches your sources
+  3. Finds relevant chunks using vector similarity
-  4. Retrieves relevant chunks
+  4. Retrieves only the most relevant pieces
-  5. Processes results
+  5. Sends ONLY those chunks to the LLM
   6. Synthesizes into comprehensive answer
 
-YOU:
+AI:
-  Get one detailed answer (not conversational)
+  - Sees ONLY the retrieved chunks (not full sources)
+  - Answers based on what was found to be relevant
+  - One-shot answer (not conversational)
 ```
 
-**Use this when**: You want a comprehensive answer and trust the AI to find what's relevant.
+**Use this when**:
+- You have many sources and don't know which are relevant
+- You want the AI to search automatically
+- You need a comprehensive answer to a complex question
+- You want to minimize tokens sent to LLM
+
+**Advantages:**
+- Automatic search (you don't pick sources)
+- Works across many sources at once
+- Cost-effective (sends only relevant chunks)
+
+**Limitations:**
+- Not conversational (single question/answer)
+- AI only sees retrieved chunks (might miss context)
+- Search quality depends on how well question matches content
 
 ---
 
@@ -380,16 +425,26 @@ This is why semantic search finds conceptually similar content even when words a
 
 ## Summary
 
-**RAG** allows Open Notebook to:
+Open Notebook gives you **two ways** to work with AI:
+
+### Chat (Full-Content)
+- Sends entire selected sources to LLM
+- Manual control: you pick sources
+- Conversational: back-and-forth dialog
+- Transparent: you know exactly what AI sees
+- Best for: focused analysis, close reading
+
+### Ask (RAG)
+- Searches and retrieves relevant chunks automatically
+- Automatic: AI finds what's relevant
+- One-shot: single comprehensive answer
+- Efficient: sends only relevant pieces
+- Best for: broad questions across many sources
+
+**Both approaches:**
 1. Keep your data private (doesn't leave your system by default)
-2. Make AI aware of your research (retrieval brings in relevant chunks)
+2. Give you control (you choose which features to use)
-3. Give you control (you decide what's in context)
+3. Create audit trails (citations show what was used)
-4. Create audit trails (citations show what was used)
+4. Support multiple AI providers
-5. Support multiple searches (keyword and semantic)
 
-This is fundamentally different from:
+**Coming Soon**: The community is working on adding RAG capabilities to Chat as well, giving you the best of both worlds.
-- Systems that fine-tune (slow, permanent)
-- Systems that send everything (privacy nightmare)
-- Systems that ignore your data (no customization)
-
-It's **retrieval-augmented generation**: the system retrieves what's relevant, then augments the AI's knowledge with it.

docs/2-CORE-CONCEPTS/chat-vs-transformations.md

@@ -93,30 +93,32 @@ You: [Get back one comprehensive answer]
 
 ---
 
-### 3. TRANSFORMATIONS - Batch Processing with Templates
+### 3. TRANSFORMATIONS - Template-Based Processing
 
-**What it is:** Apply a reusable template to one or more sources and get structured outputs.
+**What it is:** Apply a reusable template to a source and get structured output.
 
 **The flow:**
 ```
 1. You define a transformation (or choose a preset)
    "Extract: main argument, methodology, limitations"
 
-2. You apply it to one or more sources
+2. You apply it to ONE source at a time
-   OR system applies it to all sources
+   (You can repeat for other sources)
 
-3. For each source:
+3. For the source:
    - Source content + transformation prompt → AI
    - Result stored as new insight/note
 
 4. You get back
-   - Structured outputs (main argument, methodology, limitations)
+   - Structured output (main argument, methodology, limitations)
-   - Saved as notes in your notebook
+   - Saved as a note in your notebook
 ```
 
-**Context management:** You choose which sources to transform.
+**Context management:** Works on one source at a time.
 
-**Batch processing:** Process multiple sources at once.
+**Reusable:** Apply the same template to different sources (one by one).
+
+**Note**: Currently processes one source at a time. Batch processing (multiple sources at once) is planned for a future release.
 
 **Example:**
 ```
@@ -128,23 +130,24 @@ You: Define transformation
       - Limitations and gaps
       - Recommended next research"
 
-You: Apply to 10 papers
+You: Apply to paper 1
 
 System:
-  - For each paper, runs the transformation
+  - Runs the transformation on paper 1
-  - Results stored as 10 new notes
+  - Result stored as new note
-  - Each note has the structure you defined
 
-You: Now you have structured notes from all 10 papers
+You: Apply same transformation to paper 2, 3, etc.
-     Perfect for writing a literature review or comparison
+
+After 10 papers:
+  - You have 10 structured notes with consistent format
+  - Perfect for writing a literature review or comparison
 ```
 
 **Best for:**
-- Extracting the same information from multiple sources
+- Extracting the same information from each source (run repeatedly)
-- Creating structured summaries
+- Creating structured summaries with consistent format
 - Building a knowledge base of categorized insights
-- When you want consistent, reusable templates
+- When you want reusable templates you can apply to each source
-- Batch processing multiple sources
 
 ---
 
@@ -165,8 +168,8 @@ What are you trying to do?
 ├─→ "I need to compare these sources or get a comprehensive answer"
 │   └─→ USE: ASK
 │
-├─→ "I want to extract the same info from many sources"
+├─→ "I want to extract the same info from each source (one at a time)"
-│   └─→ USE: TRANSFORMATIONS
+│   └─→ USE: TRANSFORMATIONS (apply to each source)
 │
 └─→ "I just want to read and search"
     └─→ USE: Search (text or vector)
@@ -179,13 +182,13 @@ What are you trying to do?
 
 | Aspect | CHAT | ASK | TRANSFORMATIONS |
 |--------|------|-----|-----------------|
-| **What's it for?** | Conversational exploration | Comprehensive Q&A | Batch extraction |
+| **What's it for?** | Conversational exploration | Comprehensive Q&A | Template-based extraction |
-| **# of questions** | Multiple (conversational) | One | One template, many sources |
+| **# of questions** | Multiple (conversational) | One | One template per source |
-| **Context control** | Manual (you choose) | Automatic (system searches) | Manual (you choose) |
+| **Context control** | Manual (you choose) | Automatic (system searches) | One source at a time |
-| **Conversational?** | Yes (follow-ups work) | No (one question only) | No (batch process) |
+| **Conversational?** | Yes (follow-ups work) | No (one question only) | No (single operation) |
-| **Output** | Natural conversation | Natural answer | Structured notes |
+| **Output** | Natural conversation | Natural answer | Structured note |
-| **Time** | Quick (back-and-forth) | Longer (comprehensive) | Batch (all at once) |
+| **Time** | Quick (back-and-forth) | Longer (comprehensive) | Per source |
-| **Best when** | Exploring & uncertain | Need full picture | Want consistency |
+| **Best when** | Exploring & uncertain | Need full picture | Want consistent format |
 | **Model speed** | Any | Fast preferred | Any |
 
 ---
@@ -199,8 +202,10 @@ Goal: Write literature review from 15 papers
 
 Step 1: TRANSFORMATIONS
   - Define: "Extract abstract, methodology, findings, relevance"
-  - Apply to all 15 papers
+  - Apply to paper 1 → get structured note
-  - Get back 15 structured notes
+  - Apply to paper 2 → get structured note
+  - ... repeat for all 15 papers
+  - Result: 15 structured notes with consistent format
 
 Step 2: Read the notes
   - Now you have consistent summaries
@@ -231,7 +236,7 @@ Step 3: CHAT
 
 Step 4: TRANSFORMATIONS (optional)
   - Define: "Extract: pain point, frequency, who mentioned it"
-  - Apply to all interviews
+  - Apply to each interview (one by one)
   - Get structured data for analysis
 ```
 
@@ -338,11 +343,11 @@ CHAT → Save as Note → TRANSFORMATIONS
 |-----------|-----|-----|
 | "I want to explore a topic with follow-up questions" | **CHAT** | Conversational, you control context |
 | "I need a comprehensive answer to one complex question" | **ASK** | Automatic search, synthesized answer |
-| "I want consistent summaries from 10+ sources" | **TRANSFORMATIONS** | Template reuse, batch processing |
+| "I want consistent summaries from each source" | **TRANSFORMATIONS** | Template reuse, apply to each source |
 | "I'm comparing two specific sources" | **CHAT** | Select just those 2, have discussion |
-| "I need to categorize all sources by X criteria" | **TRANSFORMATIONS** | Extract category for each source |
+| "I need to categorize each source by X criteria" | **TRANSFORMATIONS** | Extract category from each source |
 | "I want to understand the big picture across all sources" | **ASK** | Automatic comprehensive search |
-| "I want to build a knowledge base" | **TRANSFORMATIONS** | Create structured notes |
+| "I want to build a knowledge base" | **TRANSFORMATIONS** | Create structured note from each source |
 | "I want to iterate on understanding" | **CHAT** | Multiple questions, refine thinking |
 
 The key insight: **Different questions need different tools.** Open Notebook gives you all three because research rarely fits one mode.

docs/2-CORE-CONCEPTS/index.md

@@ -12,16 +12,16 @@ How Open Notebook organizes your research. Understand the three-tier container s
 ---
 
 ### 2. [AI Context & RAG](ai-context-rag.md)
-How Open Notebook makes AI aware of your research without uploading everything to the cloud.
+How Open Notebook makes AI aware of your research - two different approaches.
 
-**Key idea**: RAG (Retrieval-Augmented Generation) means the AI searches your content, finds relevant pieces, and answers based on what it found. You control which content is in scope.
+**Key idea**: **Chat** sends entire selected sources to the LLM (full context, conversational). **Ask** uses RAG (retrieval-augmented generation) to automatically search and retrieve only relevant chunks. Different tools for different needs.
 
 ---
 
 ### 3. [Chat vs. Transformations](chat-vs-transformations.md)
 Why Open Notebook has different interaction modes and when to use each one.
 
-**Key idea**: Chat is conversational exploration (you control context). Transformations are batch processing (you define the template). They answer different questions.
+**Key idea**: Chat is conversational exploration (you control context). Transformations are insight extractions. They reduced content to smaller bits of concentrated/dense information, which is much more suitable for an AI to use. 
 
 ---
 
@@ -42,8 +42,8 @@ Why Open Notebook can turn research into audio and why this matters.
 ## Read This Section If:
 
 - **You're new to Open Notebook** — Start here to understand how the system works conceptually before learning the features
-- **You're confused about RAG** — Section 2 explains what it is and why it matters
+- **You're confused about Chat vs Ask** — Section 2 explains the difference (full-content vs RAG)
-- **You're wondering when to use Chat vs Ask** — Section 3 clarifies the differences
+- **You're wondering when to use Chat vs Transformations** — Section 3 clarifies the differences
 - **You want to understand privacy controls** — Section 4 shows you what you can control
 - **You're curious about podcasts** — Section 5 explains the architecture and why it's different from competitors
 

docs/5-CONFIGURATION/advanced.md

@@ -192,7 +192,7 @@ API_URL=https://mynotebook.example.com
 ### Firewall Rules
 
 Restrict access to your Open Notebook:
-- Port 8502/3000 (frontend): Only from your IP
+- Port 8502 (frontend): Only from your IP
 - Port 5055 (API): Only from frontend
 - Port 8000 (SurrealDB): Never expose to internet
 

docs/5-CONFIGURATION/server.md

@@ -139,7 +139,7 @@ Edit docker-compose.yml:
 services:
   frontend:
     ports:
-      - "8001:3000"  # Change from 8502 to 8001
+      - "8001:8502"  # Change from 8502 to 8001
 ```
 
 Access at: `http://localhost:8001`
@@ -292,7 +292,7 @@ server {
 
     # Frontend
     location / {
-        proxy_pass http://localhost:3000;
+        proxy_pass http://localhost:8502;
         proxy_http_version 1.1;
         proxy_set_header Upgrade $http_upgrade;
         proxy_set_header Connection "upgrade";

docs/6-TROUBLESHOOTING/connection-issues.md

@@ -60,7 +60,7 @@ docker compose up -d
 cat .env | grep API_URL
 
 # Should match your frontend URL:
-# Frontend: http://localhost:3000
+# Frontend: http://localhost:8502
 # API_URL: http://localhost:5055
 
 # If wrong, fix it:
@@ -292,7 +292,7 @@ docker compose restart
 ### Step 3: Access from Other Machine
 ```bash
 # In browser on other machine:
-http://192.168.1.100:3000
+http://192.168.1.100:8502
 # (or your server IP)
 ```
 
@@ -302,7 +302,7 @@ http://192.168.1.100:3000
 docker compose ps
 
 # Should show port mapping:
-# 0.0.0.0:3000->3000/tcp
+# 0.0.0.0:8502->8502/tcp
 # 0.0.0.0:5055->5055/tcp
 ```
 
@@ -311,7 +311,7 @@ docker compose ps
 # Check firewall on server
 sudo ufw status
 # May need to open ports:
-sudo ufw allow 3000
+sudo ufw allow 8502
 sudo ufw allow 5055
 
 # Check on different machine:
@@ -341,7 +341,7 @@ CORS policy: Response to preflight request doesn't pass access control check
 ```bash
 # Check browser console error for what URLs are being used
 # The error shows:
-# - Requesting from: http://localhost:3000
+# - Requesting from: http://localhost:8502
 # - Trying to reach: http://localhost:5055
 
 # Make sure API_URL matches:
@@ -364,19 +364,19 @@ docker compose ps
 # All should show "Up"
 
 # 2. Ports listening?
-netstat -tlnp | grep -E "3000|5055|8000"
+netstat -tlnp | grep -E "8502|5055|8000"
 
 # 3. API responding?
 curl http://localhost:5055/health
 
 # 4. Frontend accessible?
-curl http://localhost:3000 | head
+curl http://localhost:8502 | head
 
 # 5. Network OK?
 ping google.com
 
 # 6. No firewall?
-sudo ufw status | grep -E "5055|3000|8000"
+sudo ufw status | grep -E "5055|8502|8000"
 ```
 
 ---
@@ -384,9 +384,9 @@ sudo ufw status | grep -E "5055|3000|8000"
 ## Checklist for Remote Access
 
 - [ ] Server IP noted (e.g., 192.168.1.100)
-- [ ] Ports 3000, 5055, 8000 exposed in docker-compose
+- [ ] Ports 8502, 5055, 8000 exposed in docker-compose
 - [ ] API_URL set to server IP
-- [ ] Firewall allows ports 3000, 5055, 8000
+- [ ] Firewall allows ports 8502, 5055, 8000
 - [ ] Can reach server from client machine (ping IP)
 - [ ] All services running (docker compose ps)
 - [ ] Can curl API from client (curl http://IP:5055/health)

docs/6-TROUBLESHOOTING/quick-fixes.md

@@ -26,7 +26,7 @@ curl http://localhost:5055/health
 docker compose restart
 
 # Step 4: Try again
-# Open http://localhost:3000 in browser
+# Open http://localhost:8502 in browser
 ```
 
 **If still broken:**
@@ -70,7 +70,7 @@ docker compose logs api | grep -i "api key\|error"
 
 ## #3: "Port X already in use"
 
-**Symptom:** Docker error "Port 3000 is already allocated"
+**Symptom:** Docker error "Port 8502 is already allocated"
 
 **Cause:** Another service using that port
 
@@ -78,18 +78,18 @@ docker compose logs api | grep -i "api key\|error"
 
 ```bash
 # Option 1: Stop the other service
-# Find what's using port 3000
+# Find what's using port 8502
-lsof -i :3000
+lsof -i :8502
 # Kill it or close the app
 
 # Option 2: Use different port
 # Edit docker-compose.yml
-# Change: - "3000:3000"
+# Change: - "8502:8502"
-# To:     - "3001:3000"
+# To:     - "8503:8502"
 
 # Then restart
 docker compose restart
-# Access at: http://localhost:3001
+# Access at: http://localhost:8503
 ```
 
 ---