2 Open - Release

This refactor allows for low-level looping on the client side.

This can be used for network errors between server<>upstream reported as particles,
as well as for client<>server connections.

One special case of this is the OpenAI system to reattach to detached (background) requests,
or as an alternative to re-fetch them from the server once completed.

.claude/commands/aix/roll-aix.md

@@ -0,0 +1,20 @@
+---
+description: Increment the AIX monotonic version number
+allowed-tools: Bash(git add:*),Bash(git status:*),Bash(git commit:*),Edit,Write
+model: haiku
+disable-model-invocation: true
+---
+
+Increment `Monotonics.Aix` in `src/common/app.release.ts` and commit it.
+
+**Pre-flight checks (MUST pass or abort):**
+1. Run `git branch --show-current` - MUST be on `main` branch
+2. Run `git status src/common/app.release.ts` - file MUST be unmodified (no changes on this specific file)
+
+**Execute:**
+1. Read current `Monotonics.Aix` value from `src/common/app.release.ts`
+2. Increment by 1
+3. Update ONLY that line
+4. Run: `git add src/common/app.release.ts && git commit -m "Roll AIX"`
+
+Confirm new version number.

.claude/commands/aix/sync-anthropic-api.md

@@ -0,0 +1,31 @@
+---
+description: Sync Anthropic API implementation with latest upstream documentation
+argument-hint: specific feature to check
+---
+
+Please take a look at my API code for Anthropic: message wire types `src/modules/aix/server/dispatch/wiretypes/anthropic.wiretypes.ts`, assembly of the request messages (adapters) `src/modules/aix/server/dispatch/chatGenerate/adapters/anthropic.messageCreate.ts`, and parsing of the response in streaming or not `src/modules/aix/server/dispatch/chatGenerate/parsers/anthropic.parser.ts`.
+
+IMPORTANT: we only support the Messages API (message create). We do NOT support other APIs such as the older Completions API.
+We support Anthropic caching natively, and want to make sure tools and state (crafting the history) are also done well.
+
+Then take a look at the newest API information available. Try these sources, and be creative if some are blocked:
+
+**Primary Sources:**
+- Docs API: https://docs.claude.com/en/api/messages
+- Release notes: https://docs.claude.com/en/release-notes/api
+- Tools use: https://docs.claude.com/en/docs/agents-and-tools/tool-use/overview
+- Handling stop reasons: https://docs.claude.com/en/api/handling-stop-reasons
+
+**Alternative Sources if primary blocked:**
+- Anthropic TypeScript SDK: https://github.com/anthropics/anthropic-sdk-typescript
+- Anthropic Python SDK: https://github.com/anthropics/anthropic-sdk-python
+- Recent news and announcements: Web Search for "anthropic api changelog" or "new claude api" or "new claude api pricing"
+
+**If all blocked:** Explain what you attempted and ask user to provide documentation manually.
+
+$ARGUMENTS
+Check carefully and look if there are any discrepancies in the protocols, the available API surface, the structure of the messages, functionality, logic, etc.
+Make sure you look deep in the fields of the requests and responses, especially required fields, streaming event types, and any new response shapes.
+
+Please point out all of the differences in the API whether it's in the final parsing and reassembly of the streaming message, or the protocol changed, etc.
+Prioritize breaking changes and new capabilities that would improve the user experience.

.claude/commands/aix/sync-gemini-api.md

@@ -0,0 +1,30 @@
+---
+description: Sync Google Gemini API implementation with latest upstream documentation
+argument-hint: specific feature to check
+---
+
+Please take a look at my API code for Google Gemini: message wire types `src/modules/aix/server/dispatch/wiretypes/gemini.wiretypes.ts`, assembly of the request messages (adapters) `src/modules/aix/server/dispatch/chatGenerate/adapters/gemini.generateContent.ts`, and parsing of the response in streaming or not `src/modules/aix/server/dispatch/chatGenerate/parsers/gemini.parser.ts`.
+
+IMPORTANT: we only support the generateContent API, not other Gemini APIs such as embeddings, etc.
+Caching is only supported when implicit, we do not explicitly manage Gemini Caches. Same for file uploads and other systems.
+Image generation happens through models, i.e. 'Gemini 2.5 Flash - Nano Banana' generates images using AIX from generateContent (chat input).
+
+Then take a look at the newest API information available. Try these sources, and be creative if some are blocked:
+
+**Primary Sources:**
+- Docs API 1/2: https://ai.google.dev/api/generate-content
+- Docs API 2/2: https://ai.google.dev/api/caching#Content
+- Release notes: https://ai.google.dev/gemini-api/docs/changelog
+
+**Alternative Sources if primary blocked:**
+- Google AI JavaScript SDK: https://github.com/googleapis/js-genai (check latest commits, README, type definitions)
+  Recent news and announcements: Web Search for "gemini api changelog" or "nwe gemini api updates" or "new gemini api pricing"
+
+**If all blocked:** Explain what you attempted and ask user to provide documentation manually.
+
+$ARGUMENTS
+Check carefully and look if there are any discrepancies in the protocols, the available API surface, the structure of the messages, functionality, logic, etc.
+Make sure you look deep in the fields of the requests and responses, especially required fields, streaming event types, and any new response shapes.
+
+Please point out all of the differences in the API whether it's in the final parsing and reassembly of the streaming message, or the protocol changed, etc.
+Prioritize breaking changes and new capabilities that would improve the user experience.

.claude/commands/aix/sync-openai-apis.md

@@ -0,0 +1,34 @@
+---
+description: Sync OpenAI API implementation with latest upstream documentation
+argument-hint: specific feature to check
+---
+
+Please take a look at my API code for OpenAI: message wire types `src/modules/aix/server/dispatch/wiretypes/openai.wiretypes.ts`, assembly of the request messages (adapters) `src/modules/aix/server/dispatch/chatGenerate/adapters/openai.chatCompletions.ts`, and parsing of the response in streaming or not `src/modules/aix/server/dispatch/chatGenerate/parsers/openai.parser.ts`.
+
+IMPORTANT: we prioritize the new Responses API, while Chat Completions is still supported but legacy.
+We do NOT support other APIs such as Realtime (incl. websockets), etc.
+We also do not support Agentic APIs (Agent SDK, AgentKit, ChatKit, Assistants API etc), as we perform similar functionality in AIX (server or client side).
+
+Then take a look at the newest API information available. Try these sources, and be creative if some are blocked:
+
+**Primary Sources:**
+- Responses API (AIX prioritizes it): https://platform.openai.com/docs/api-reference/responses/create
+- Chat Completions API: https://platform.openai.com/docs/api-reference/chat/create
+- Changelog: https://platform.openai.com/docs/changelog
+- Models: https://platform.openai.com/docs/models
+- Pricing (use Copy Page button to download markdown): https://platform.openai.com/docs/pricing
+
+**Alternative Sources if primary blocked:**
+- OpenAI Node.js SDK: https://github.com/openai/openai-node
+- OpenAI Python SDK: https://github.com/openai/openai-python
+- OpenAI OpenAPI spec: https://github.com/openai/openai-openapi
+  Recent news and announcements: Web Search for "openai api changelog" or "openai new models" or "openai new prices"
+
+**If all blocked:** Explain what you attempted and ask user to provide documentation manually.
+
+$ARGUMENTS
+Check carefully and look if there are any discrepancies in the protocols, the available API surface, the structure of the messages, functionality, logic, etc.
+Make sure you look deep in the fields of the requests and responses, especially required fields, streaming event types, and any new response shapes.
+
+Please point out all of the differences in the API whether it's in the final parsing and reassembly of the streaming message, or the protocol changed, etc.
+Prioritize breaking changes and new capabilities that would improve the user experience.

.claude/commands/llms/update-models-alibaba.md

@@ -0,0 +1,20 @@
+---
+description: Update Alibaba model definitions with latest pricing and capabilities
+---
+
+Update `src/modules/llms/server/openai/models/alibaba.models.ts` with latest model definitions.
+
+Reference `src/modules/llms/server/llm.server.types.ts` and `src/modules/llms/server/models.data.ts` for context only. Focus on the model file, do not descend into other code.
+
+**Primary Sources:**
+- Models & Pricing: https://www.alibabacloud.com/help/en/model-studio/models
+- Billing Guide: https://www.alibabacloud.com/help/en/model-studio/billing-for-model-studio
+
+**Fallbacks if blocked:**
+- Search "alibaba model studio latest pricing", "alibaba latest models", "qwen models pricing", or search GitHub for latest model prices and context windows
+
+**Important:**
+- Review the full model list for additions, removals, and price changes
+- Minimize whitespace/comment changes, focus on content
+- Preserve comments to make diffs easy to review
+- Flag broken links or unexpected content

.claude/commands/llms/update-models-anthropic.md

@@ -0,0 +1,20 @@
+---
+description: Update Anthropic model definitions with latest pricing and capabilities
+---
+
+Update `src/modules/llms/server/anthropic/anthropic.models.ts` with latest model definitions.
+
+Reference `src/modules/llms/server/llm.server.types.ts` and `src/modules/llms/server/models.data.ts` for context only. Focus on the model file, do not descend into other code.
+
+**Primary Sources:**
+- Models: https://docs.claude.com/en/docs/about-claude/models/overview
+- Pricing: https://claude.com/pricing#api
+- Deprecations: https://docs.claude.com/en/docs/about-claude/model-deprecations
+
+**Fallbacks if blocked:** Check Anthropic TypeScript SDK at https://github.com/anthropics/anthropic-sdk-typescript, search "anthropic models latest pricing", "anthropic latest models", or search GitHub for latest model prices and context windows
+
+**Important:**
+- Review the full model list for additions, removals, and price changes
+- Minimize whitespace/comment changes, focus on content
+- Preserve comments to make diffs easy to review
+- Flag broken links or unexpected content

.claude/commands/llms/update-models-deepseek.md

@@ -0,0 +1,22 @@
+---
+description: Update DeepSeek model definitions with latest pricing and capabilities
+---
+
+Update `src/modules/llms/server/openai/models/deepseek.models.ts` with latest model definitions.
+
+Reference `src/modules/llms/server/llm.server.types.ts` and `src/modules/llms/server/models.data.ts` for context only. Focus on the model file, do not descend into other code.
+
+**Primary Sources:**
+- Pricing: https://api-docs.deepseek.com/quick_start/pricing
+- Model List: https://api-docs.deepseek.com/api/list-models
+- Release Notes: https://api-docs.deepseek.com/updates (check for version updates like V3.2-Exp)
+
+**Note:** DeepSeek frequently releases new versions with significant pricing changes. Always check release notes first.
+
+**Fallbacks if blocked:** Search "deepseek api latest pricing", "deepseek latest models", "deepseek models list" or search GitHub for latest model prices and context windows
+
+**Important:**
+- Review the full model list for additions, removals, and price changes
+- Minimize whitespace/comment changes, focus on content
+- Preserve comments to make diffs easy to review
+- Flag broken links or unexpected content

.claude/commands/llms/update-models-gemini.md

@@ -0,0 +1,21 @@
+---
+description: Update Gemini model definitions with latest pricing and capabilities
+---
+
+Update `src/modules/llms/server/gemini/gemini.models.ts` with latest model definitions.
+
+Reference `src/modules/llms/server/llm.types.ts`, `src/modules/llms/server/llm.server.types.ts`, and `src/modules/llms/server/models.data.ts` for context only. Focus on the model file, do not descend into other code.
+
+**Primary Sources:**
+- Models: https://ai.google.dev/gemini-api/docs/models
+- Pricing: https://ai.google.dev/gemini-api/docs/pricing
+- Changelog: https://ai.google.dev/gemini-api/docs/changelog
+
+**Fallbacks if blocked:** Check Google AI JS SDK at https://github.com/googleapis/js-genai, search "gemini models latest pricing", "gemini latest models", or search GitHub for latest model prices and context windows
+
+**Important:**
+- Ignore context windows (auto-determined at runtime) and training cutoffs (not supported)
+- Review the full model list for additions, removals, and price changes
+- Minimize whitespace/comment changes, focus on content
+- Preserve comments to make diffs easy to review, do NOT remove comments
+- Flag broken links or unexpected content

.claude/commands/llms/update-models-groq.md

@@ -0,0 +1,19 @@
+---
+description: Update Groq model definitions with latest pricing and capabilities
+---
+
+Update `src/modules/llms/server/openai/models/groq.models.ts` with latest model definitions.
+
+Reference `src/modules/llms/server/llm.server.types.ts` and `src/modules/llms/server/models.data.ts` for context only. Focus on the model file, do not descend into other code.
+
+**Primary Sources:**
+- Models: https://console.groq.com/docs/models
+- Pricing: https://groq.com/pricing/
+
+**Fallbacks if blocked:** Search "groq models latest pricing", "groq latest models", "groq api models", or search GitHub for latest model prices and context windows
+
+**Important:**
+- Review the full model list for additions, removals, and price changes
+- Minimize whitespace/comment changes, focus on content
+- Preserve comments to make diffs easy to review
+- Flag broken links or unexpected content

.claude/commands/llms/update-models-mistral.md

@@ -0,0 +1,24 @@
+---
+description: Update Mistral model definitions with latest pricing and capabilities
+---
+
+Update `src/modules/llms/server/openai/models/mistral.models.ts` with latest model definitions.
+
+Reference `src/modules/llms/server/llm.server.types.ts` and `src/modules/llms/server/models.data.ts` for context only. Focus on the model file, do not descend into other code.
+
+**Primary Sources:**
+- Models: https://docs.mistral.ai/getting-started/models/models_overview/
+- Pricing: https://mistral.ai/pricing#api-pricing
+- Changelog: https://docs.mistral.ai/getting-started/changelog/
+
+**Fallbacks if blocked:**
+- Search "mistral [model-name] latest pricing",  "mistral api latest pricing", "mistral latest models", or search GitHub for latest model prices and context windows
+- Cross-reference: pricepertoken.com, helicone.ai, artificialanalysis.ai
+- Check Mistral API list models response
+- As last resort: Use Chrome DevTools MCP to render pricing table
+
+**Important:**
+- Review the full model list for additions, removals, and price changes
+- Minimize whitespace/comment changes, focus on content
+- Preserve comments to make diffs easy to review
+- Flag broken links or unexpected content

.claude/commands/llms/update-models-ollama.md

@@ -0,0 +1,40 @@
+---
+description: Update Ollama model definitions with latest featured models
+---
+
+Update `src/modules/llms/server/ollama/ollama.models.ts` with latest model definitions.
+
+Reference `src/modules/llms/server/llm.server.types.ts` and `src/modules/llms/server/models.data.ts` for context only. Focus on the model file, do not descend into other code.
+
+**Automated Workflow:**
+```bash
+# 1. Fetch the HTML
+curl -s "https://ollama.com/library?sort=featured" -o /tmp/ollama-featured.html
+
+# 2. Parse it with the script
+node .claude/scripts/parse-ollama-models.js > /tmp/ollama-parsed.txt 2>&1
+
+# 3. Review the parsed output
+cat /tmp/ollama-parsed.txt
+```
+
+The parser outputs: `modelName|pulls|capabilities|sizes`
+- Example: `deepseek-r1|66200000|tools,thinking|1.5b,7b,8b,14b,32b,70b,671b`
+
+**Primary Sources:**
+- Model Library: https://ollama.com/library?sort=featured
+- Parser script: `.claude/scripts/parse-ollama-models.js`
+
+**Fallbacks if blocked:** Check https://github.com/ollama/ollama, search "ollama featured models", "ollama latest models", or search GitHub for latest model info
+
+**Important:**
+- Skip models below 50,000 pulls (parser does this automatically)
+- Sort them in the EXACT same order as the source (featured models)
+- Extract tags: 'tools' → hasTools, 'vision' → hasVision, 'embedding' → isEmbeddings (note the 's'), 'thinking' → tags only
+- Extract 'b' tags (1.5b, 7b, 32b) to tags field
+- Set today's date (YYYYMMDD format) for newly added models only
+- Update OLLAMA_LAST_UPDATE constant to today's date
+- Do NOT change dates of existing models
+- Review the full model list for additions, removals, and changes
+- Minimize whitespace/comment changes, focus on content
+- Preserve comments and newlines to make diffs easy to review

.claude/commands/llms/update-models-openai.md

@@ -0,0 +1,26 @@
+---
+description: Update OpenAI model definitions with latest pricing and capabilities
+---
+
+Update `src/modules/llms/server/openai/models/openai.models.ts` with latest model definitions.
+
+Reference `src/modules/llms/server/llm.server.types.ts` and `src/modules/llms/server/models.data.ts` for context only. Focus on the model file, do not descend into other code.
+
+**Manual hint:** For pricing page, expand all tables before copying content.
+
+**Primary Sources:**
+- Models: https://platform.openai.com/docs/models (use Copy Page button)
+- Pricing: https://platform.openai.com/docs/pricing (expand tables first)
+
+**Known Issue:** OpenAI docs block automated access (403 Forbidden). Manual browser access required.
+
+**Fallbacks if blocked:**
+- Search "openai models latest pricing", "openai latest models" for third-party aggregators, or search GitHub for latest model prices and context windows
+- OpenAI Node SDK (https://github.com/openai/openai-node) has limited model metadata only
+- As last resort: Use Chrome DevTools MCP to navigate and extract from official docs
+
+**Important:**
+- Review the full model list for additions, removals, and price changes
+- Minimize whitespace/comment changes, focus on content
+- Preserve comments to make diffs easy to review
+- Flag broken links or unexpected content

.claude/commands/llms/update-models-openpipe.md

@@ -0,0 +1,19 @@
+---
+description: Update OpenPipe model definitions with latest pricing and capabilities
+---
+
+Update `src/modules/llms/server/openai/models/openpipe.models.ts` with latest model definitions.
+
+Reference `src/modules/llms/server/llm.server.types.ts` and `src/modules/llms/server/models.data.ts` for context only. Focus on the model file, do not descend into other code.
+
+**Primary Sources:**
+- Base Models: https://docs.openpipe.ai/base-models
+- Pricing: https://docs.openpipe.ai/pricing/pricing
+
+**Fallbacks if blocked:** Search "openpipe models latest pricing", "openpipe latest models", "openpipe base models", or search GitHub for latest model prices and context windows
+
+**Important:**
+- Review the full model list for additions, removals, and price changes
+- Minimize whitespace/comment changes, focus on content
+- Preserve comments to make diffs easy to review
+- Flag broken links or unexpected content

.claude/commands/llms/update-models-perplexity.md

@@ -0,0 +1,20 @@
+---
+description: Update Perplexity model definitions with latest pricing and capabilities
+---
+
+Update `src/modules/llms/server/openai/models/perplexity.models.ts` with latest model definitions.
+
+Reference `src/modules/llms/server/llm.server.types.ts` and `src/modules/llms/server/models.data.ts` for context only. Focus on the model file, do not descend into other code.
+
+**Primary Sources:**
+- Models: https://docs.perplexity.ai/getting-started/models
+- Pricing: https://docs.perplexity.ai/getting-started/pricing
+- Changelog: https://docs.perplexity.ai/changelog/changelog
+
+**Fallbacks if blocked:** Search "perplexity api latest pricing", "perplexity latest models", or search GitHub for latest model prices and context windows
+
+**Important:**
+- Review the full model list for additions, removals, and price changes
+- Minimize whitespace/comment changes, focus on content
+- Preserve comments to make diffs easy to review
+- Flag broken links or unexpected content

.claude/commands/llms/update-models-xai.md

@@ -0,0 +1,23 @@
+---
+description: Update xAI model definitions with latest pricing and capabilities
+---
+
+Update `src/modules/llms/server/openai/models/xai.models.ts` with latest model definitions.
+
+Reference `src/modules/llms/server/llm.server.types.ts` and `src/modules/llms/server/models.data.ts` for context only. Focus on the model file, do not descend into other code.
+
+**Primary Sources:**
+- Models & Pricing: https://docs.x.ai/docs/models?cluster=us-east-1#detailed-pricing-for-all-grok-models
+
+**Known Issue:** docs.x.ai blocks automated access (403 Forbidden). Use fallbacks below.
+
+**Fallbacks if blocked:**
+- Search "xai grok latest pricing", "xai latest models", "xai api models", or search GitHub for latest model prices and context windows
+- Random sites? https://the-rogue-marketing.github.io/grok-api-latest-llms-pricing-october-2025/ (find a newer version), https://langdb.ai/app/providers/xai/ (browse by model, limited coverage)
+- As last resort: Use Chrome DevTools MCP to access docs.x.ai
+
+**Important:**
+- Review the full model list for additions, removals, and price changes
+- Minimize whitespace/comment changes, focus on content
+- Preserve comments to make diffs easy to review
+- Flag broken links or unexpected content

.claude/scripts/parse-ollama-models.js

@@ -0,0 +1,81 @@
+#!/usr/bin/env node
+/**
+ * Parse Ollama featured models from HTML
+ *
+ * Usage:
+ *   1. Fetch HTML: curl -s "https://ollama.com/library?sort=featured" -o /tmp/ollama-featured.html
+ *   2. Parse: node .claude/scripts/parse-ollama-models.js
+ *
+ * Outputs: pipe-delimited format: modelName|pulls|capabilities|sizes
+ * Example: deepseek-r1|66200000|tools,thinking|1.5b,7b,8b,14b,32b,70b,671b
+ */
+
+const fs = require('fs');
+
+const htmlPath = process.argv[2] || '/tmp/ollama-featured.html';
+
+if (!fs.existsSync(htmlPath)) {
+  console.error(`Error: HTML file not found at ${htmlPath}`);
+  console.error('Please fetch it first with:');
+  console.error('  curl -s "https://ollama.com/library?sort=featured" -o /tmp/ollama-featured.html');
+  process.exit(1);
+}
+
+const html = fs.readFileSync(htmlPath, 'utf8');
+
+// Split into model sections - each starts with <a href="/library/
+const modelSections = html.split(/<a href="\/library\//);
+const models = [];
+
+for (let i = 1; i < modelSections.length; i++) {
+  const section = modelSections[i].substring(0, 5000); // Large enough window to capture all data
+
+  // Extract model name (first quoted string)
+  const nameMatch = section.match(/^([^"]+)"/);
+  if (!nameMatch) continue;
+  const name = nameMatch[1];
+
+  // Extract pulls using x-test-pull-count
+  const pullsMatch = section.match(/x-test-pull-count>([^<]+)</);
+  let pulls = 0;
+  if (pullsMatch) {
+    const pullStr = pullsMatch[1].replace(/,/g, '');
+    if (pullStr.includes('M')) {
+      pulls = Math.floor(parseFloat(pullStr) * 1000000);
+    } else if (pullStr.includes('K')) {
+      pulls = Math.floor(parseFloat(pullStr) * 1000);
+    } else {
+      pulls = parseInt(pullStr);
+    }
+  }
+
+  // Extract capabilities (tools, vision, embedding, thinking, cloud)
+  const capabilities = [];
+  const capabilityRegex = /x-test-capability[^>]*>([^<]+)</g;
+  let capMatch;
+  while ((capMatch = capabilityRegex.exec(section)) !== null) {
+    capabilities.push(capMatch[1].trim());
+  }
+
+  // Extract sizes (1.5b, 7b, etc.)
+  const sizes = [];
+  const sizeRegex = /x-test-size[^>]*>([^<]+)</g;
+  let sizeMatch;
+  while ((sizeMatch = sizeRegex.exec(section)) !== null) {
+    sizes.push(sizeMatch[1].trim());
+  }
+
+  // Only include models with 50K+ pulls
+  if (pulls >= 50000) {
+    models.push({ name, pulls, capabilities, sizes });
+  }
+}
+
+// Output in pipe-delimited format (in the order they appear on the page)
+models.forEach(m => {
+  const caps = m.capabilities.join(',');
+  const tags = m.sizes.join(',');
+  console.log(`${m.name}|${m.pulls}|${caps}|${tags}`);
+});
+
+console.error(`\nTotal models with 50K+ pulls: ${models.length}`);

.claude/settings.local.json

@@ -0,0 +1,35 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(cat:*)",
+      "Bash(cp:*)",
+      "Bash(find:*)",
+      "Bash(git branch:*)",
+      "Bash(git describe:*)",
+      "Bash(git log:*)",
+      "Bash(git log:*)",
+      "Bash(git show:*)",
+      "Bash(grep:*)",
+      "Bash(ls:*)",
+      "Bash(mkdir:*)",
+      "Bash(node:*)",
+      "Bash(npm install)",
+      "Bash(npm install:*)",
+      "Bash(npm run:*)",
+      "Bash(npx tsc:*)",
+      "Bash(rg:*)",
+      "Bash(rm:*)",
+      "Bash(sed:*)",
+      "WebFetch",
+      "WebFetch(domain:big-agi.com)",
+      "WebSearch",
+      "mcp__chrome-devtools",
+      "mcp__github",
+      "mcp__ide__getDiagnostics"
+    ],
+    "deny": [
+      "Read(node_modules)",
+      "Read(node_modules/**)"
+    ]
+  }
+}

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -5,14 +5,29 @@ labels: [ 'type: bug' ]
 body:
   - type: markdown
     attributes:
-      value: Thank you for reporting a bug.
+      value: Thank you for reporting a bug. Please help us by providing accurate environment information.
+
+  - type: dropdown
+    attributes:
+      label: Environment
+      description: (required) Where are you experiencing this issue?
+      options:
+        - Big-AGI Pro (big-agi.com)
+        - Self-deployed from GitHub
+        - Docker container (specify in description)
+        - Local development
+        - Other
+    validations:
+      required: true
+
   - type: textarea
     attributes:
       label: Description
-      description: (required) Please provide a clear description. Please also provide the steps to reproduce.
+      description: (required) Please provide a clear description and **steps to reproduce**.
       placeholder: 'Concise description + steps to reproduce.'
     validations:
       required: true
+
   - type: textarea
     attributes:
       label: Device and browser
@@ -20,10 +35,12 @@ body:
       placeholder: 'Device: (e.g., iPhone 16, Pixel 9, PC, Macbook...), OS: (e.g., iOS 17, Windows 12), Browser: (e.g., Chrome 119, Safari 18, Firefox..)'
     validations:
       required: true
+
   - type: textarea
     attributes:
       label: Screenshots and more
       placeholder: 'Attach screenshots, or add any additional context here.'
+
   - type: checkboxes
     attributes:
       label: Willingness to Contribute

.github/ISSUE_TEMPLATE/maintainers-release.md

@@ -32,7 +32,6 @@ assignees: enricoros
   - [ ] verify deployment on Vercel
   - [ ] verify container on GitHub Packages
   - [ ] update the GitHub release
-  - [ ] push as stable `git push opensource main:main-stable`
 - Announce:
   - [ ] Discord announcement
   - [ ] Twitter announcement

.github/workflows/claude-dm.yml

@@ -0,0 +1,57 @@
+name: Claude Code DM
+
+on:
+  issues:
+    types: [opened, assigned]
+  issue_comment:
+    types: [created]
+  pull_request_review:
+    types: [submitted]
+  pull_request_review_comment:
+    types: [created]
+
+jobs:
+  claude-dm:
+    if: |
+      (github.event_name == 'issues' && (contains(github.event.issue.body, '@claude') || contains(github.event.issue.title, '@claude'))) ||
+      (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')) ||
+      (github.event_name == 'pull_request_review' && contains(github.event.review.body, '@claude')) ||
+      (github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude'))
+
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+
+    permissions:
+      contents: read
+      pull-requests: write
+      issues: write
+      id-token: write
+      actions: read # Required for Claude to read CI results on PRs
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+
+      - name: Run Claude Code DM Response
+        id: claude
+        uses: anthropics/claude-code-action@v1
+        with:
+          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+
+          # Security: Only users with write access can trigger (DMs allow code execution)
+
+          # This is an optional setting that allows Claude to read CI results on PRs
+          additional_permissions: |
+            actions: read
+
+          # Optional: Add claude_args to customize behavior and configuration
+          # See https://github.com/anthropics/claude-code-action/blob/main/docs/usage.md
+          # or https://docs.claude.com/en/docs/claude-code/cli-reference for available options
+          # claude_args: '--allowed-tools Bash(gh pr:*)'
+          # disabling opus for now claude-opus-4-1-20250805
+          claude_args: |
+            --model claude-sonnet-4-5-20250929
+            --max-turns 100
+            --allowedTools "Edit,Read,Write,WebFetch,WebSearch,Bash(cat:*),Bash(cp:*),Bash(find:*),Bash(git branch:*),Bash(grep:*),Bash(ls:*),Bash(mkdir:*),Bash(npm install),Bash(npm install:*),Bash(npm run:*),Bash(gh issue:*),Bash(gh search:*),Bash(gh label:*),Bash(gh pr:*),mcp__chrome-devtools,SlashCommand"

.github/workflows/claude-issue-triage.yml

@@ -0,0 +1,71 @@
+name: Claude Code Auto-Triage Issues
+
+on:
+  issues:
+    types: [ opened, assigned ]
+
+jobs:
+  claude-issue-triage:
+    # Optional: Skip for bot users and direct mentions in the body (handled by claude-dm.yml)
+    if: |
+      github.event.issue.user.type != 'Bot' &&
+      !contains(github.event.issue.body, '@claude')
+
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+
+    permissions:
+      contents: read
+      issues: write
+      pull-requests: read
+      id-token: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+
+      - name: Analyze issue and provide help
+        uses: anthropics/claude-code-action@v1
+        with:
+          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+          # Security: Allow any user to trigger triage (automated issue help is safe)
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          allowed_non_write_users: '*'
+          # track_progress: true # Enables tracking comments
+
+          prompt: |
+            REPO: ${{ github.repository }}
+            ISSUE NUMBER: #${{ github.event.issue.number }}
+
+            A user has reported an issue. Please help them by:
+
+            1. Deep think about the issue:
+               **Understand the problem**: Analyze the issue description and any error messages
+               **Search for context**:
+               - Use the repository's CLAUDE.md for high level guidance and especially kb/ documentation
+               - Look in relevant code files, including kb/ documentation
+               **Use web search**: When potentially outside Big-AGI (e.g. user configuration), search the web for similar errors or related issues
+               **Provide a solution**:
+               - Provide multiple solutions if uncertain, and say so
+               - If you can fix it in code, propose the fix
+                 - If possible also suggest fixes or workarounds for immediate relief
+               - Reference specific files and line numbers
+               - Test selectively and even npm install and run build if needed to verify the solution
+            2. Always add the 'claude-triage' issue label to indicate this issue was triaged by Claude
+            3. Comment with:
+               - Very brief thank you note, if applicable
+               - Initial assessment
+               - Next steps or clarification needed
+               - Link duplicates if found
+            
+            If you're uncertain, say so and suggest next steps.
+            Be welcoming, helpful, professional, solution-focused and no-BS.
+
+          # See https://github.com/anthropics/claude-code-action/blob/main/docs/usage.md
+          # or https://docs.claude.com/en/docs/claude-code/cli-reference for available options
+          claude_args: |
+            --model claude-sonnet-4-5-20250929
+            --max-turns 60
+            --allowedTools "Edit,Read,Write,WebFetch,WebSearch,Bash(cat:*),Bash(cp:*),Bash(find:*),Bash(git branch:*),Bash(grep:*),Bash(ls:*),Bash(mkdir:*),Bash(npm install),Bash(npm install:*),Bash(npm run:*),Bash(gh issue:*),Bash(gh search:*),Bash(gh label:*),Bash(gh pr:*),mcp__chrome-devtools,SlashCommand"

.github/workflows/claude-pr-review.yml

@@ -0,0 +1,77 @@
+name: Claude Code PR Review
+
+on:
+  pull_request:
+    types: [ opened, synchronize, ready_for_review ]
+
+    # Limit branches
+    branches: [ main, dev, v1 ]
+
+    # Optional: Only run on specific file changes
+    # paths:
+    #   - "src/**/*.ts"
+    #   - "src/**/*.tsx"
+
+jobs:
+  claude-pr-review:
+    # Skip draft PRs
+    # Optional: filter authors: github.event.pull_request.user.login != 'enricoros'
+    if: |
+      github.event.pull_request.draft == false
+
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+
+    permissions:
+      contents: read
+      pull-requests: write
+      issues: read
+      id-token: write
+      actions: read # Required for Claude to read CI results on PRs
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+
+      - name: Run PR Review
+        uses: anthropics/claude-code-action@v1
+        with:
+          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+          # Security: Allow any user to trigger reviews (read-only PR analysis is safe)
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          allowed_non_write_users: '*'
+          # track_progress: true # Enables tracking comments
+
+          # This setting allows Claude to read CI results on PRs
+          additional_permissions: |
+            actions: read
+
+          prompt: |
+            REPO: ${{ github.repository }}
+            PR NUMBER: ${{ github.event.pull_request.number }}
+
+            Please review this pull request and provide feedback on:
+            - Potential bugs or issues
+            - Adherence to Big-AGI architecture and design patterns
+            - Code quality and best practices, including TypeScript types, error handling, and edge cases
+            - Performance considerations: bundle size, React patterns, streaming efficiency
+            - Security concerns if applicable
+
+            Use the repository's CLAUDE.md for guidance on style and conventions.
+
+            Use `gh pr comment` with your Bash tool to leave your review as a comment on the PR.
+            Use `gh pr review comment` for inline suggestions on specific lines.
+
+            IMPORTANT: After completing your review, always add the 'claude-review' label to the PR to indicate it was reviewed by Claude:
+            gh pr edit ${{ github.event.pull_request.number }} --add-label "claude-review"
+
+            Be constructive, helpful, no-BS, and specific with file:line references.
+
+          # See https://github.com/anthropics/claude-code-action/blob/main/docs/usage.md
+          # or https://docs.claude.com/en/docs/claude-code/cli-reference for available options
+          claude_args: |
+            --model claude-sonnet-4-5-20250929
+            --max-turns 100
+            --allowedTools "Edit,Read,Write,WebFetch,WebSearch,Bash(cat:*),Bash(cp:*),Bash(find:*),Bash(git branch:*),Bash(grep:*),Bash(ls:*),Bash(mkdir:*),Bash(npm install),Bash(npm install:*),Bash(npm run:*),Bash(gh issue:*),Bash(gh search:*),Bash(gh label:*),Bash(gh pr:*),mcp__chrome-devtools"

.github/workflows/docker-image.yml

@@ -12,10 +12,9 @@ name: Create and publish Docker images
 on:
   push:
     branches:
-      - main
-      #- main-stable  # Disabled as the v* tag is used for stable releases
+      - main          # Primary branch (Big-AGI Open)
     tags:
-      - 'v*'  # Trigger on version tags (e.g., v1.7.0)
+      - 'v2.*'        # Stable releases (v2.0.0, v2.1.0, etc.)
 
 env:
   REGISTRY: ghcr.io
@@ -27,13 +26,22 @@ jobs:
     permissions:
       contents: read
       packages: write
+      security-events: write
 
     steps:
       - name: Checkout repository
         uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@v3
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
 
       - name: Log in to the Container registry
-        uses: docker/login-action@65b78e6e13532edd9afa3aa52ac7964289d1a9c1
+        uses: docker/login-action@v3
         with:
           registry: ${{ env.REGISTRY }}
           username: ${{ github.actor }}
@@ -41,21 +49,44 @@ jobs:
 
       - name: Extract metadata (tags, labels) for Docker
         id: meta
-        uses: docker/metadata-action@9ec57ed1fcdbf14dcef7dfbe97b2010124a938b7
+        uses: docker/metadata-action@v5
         with:
           images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
           tags: |
+            # Development: main branch
             type=raw,value=development,enable=${{ github.ref == 'refs/heads/main' }}
-            type=raw,value=stable,enable=${{ github.ref == 'refs/heads/main-stable' }}
-            type=ref,event=tag  # Use the tag name as a tag for tag builds
-            type=semver,pattern={{version}}  # Generate semantic versioning tags for tag builds
+
+            # Latest: v2.x releases (safe default)
+            type=raw,value=latest,enable=${{ startsWith(github.ref, 'refs/tags/v2.') }}
+
+            # Stable: v2.x releases (alias)
+            type=raw,value=stable,enable=${{ startsWith(github.ref, 'refs/tags/v2.') }}
+
+            # Version tags (v2.0.0, 2.0.0)
+            type=ref,event=tag
+            type=semver,pattern={{version}}
+          labels: |
+            org.opencontainers.image.title=Big-AGI Open
+            org.opencontainers.image.description=Big-AGI Open - Multi-model AI workspace for experts who need to think broader, decide smarter, and build with confidence.
+            org.opencontainers.image.source=${{ github.server_url }}/${{ github.repository }}
+            org.opencontainers.image.documentation=https://big-agi.com
 
       - name: Build and push Docker image
-        uses: docker/build-push-action@f2a1d5e99d037542a71f64918e516c093c6f3fc4
+        uses: docker/build-push-action@v6
         with:
           context: .
           file: Dockerfile
+          platforms: linux/amd64,linux/arm64
           push: true
           tags: ${{ steps.meta.outputs.tags }}
           labels: ${{ steps.meta.outputs.labels }}
-          build-args: NEXT_PUBLIC_GA4_MEASUREMENT_ID=${{ secrets.GA4_MEASUREMENT_ID }}
+          build-args: |
+            NEXT_PUBLIC_GA4_MEASUREMENT_ID=${{ secrets.GA4_MEASUREMENT_ID }}
+            NEXT_PUBLIC_BUILD_HASH=${{ github.sha }}
+            NEXT_PUBLIC_BUILD_REF_NAME=${{ github.ref_name }}
+          # Enable build cache (future)
+          #cache-from: type=gha
+          #cache-to: type=gha,mode=max
+          # Enable provenance and SBOM (future)
+          #provenance: true
+          #sbom: true

.gitignore

@@ -3,6 +3,10 @@
 # Frontend Build: ignore API files disabled for this build
 /app/**/*.backup
 
+# Supabase - ignored for now
+/supabase/
+/*.sql
+
 # dependencies
 /node_modules
 /.pnp
@@ -41,4 +45,11 @@ yarn-error.log*
 next-env.d.ts
 
 # other
-.idea/
+.idea/
+
+# Ingore k8s/env-secret.yaml
+./k8s/env-secret.yaml
+/certificates
+.env*.local
+/.run/dev (ENV).run.xml
+/src/modules/3rdparty/aider/scratch*

CLAUDE.md

@@ -0,0 +1,241 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Development Commands
+
+```bash
+# Targeted Code Quality (safe while dev server runs)
+npx tsc --noEmit                      # Type check without building
+npx eslint src/path/to/file.ts        # Lint specific file
+npm run lint                          # Lint entire project
+```
+
+## Architecture Overview
+
+Big-AGI is a Next.js 15 application with a modular architecture built for advanced AI interactions. The codebase follows a three-layer structure with distinct separation of concerns.
+
+### Core Directory Structure
+
+```
+/app/api/          # Next.js App Router (API routes only, mostly -> /src/server/)
+/pages/            # Next.js Pages Router (file-based, mostly -> /src/apps/)
+/src/
+├── apps/          # Feature applications (self-contained modules)
+├── modules/       # Reusable business logic and integrations
+├── common/        # Shared infrastructure and utilities
+└── server/        # Backend API layer with tRPC
+/kb/               # Knowledge base for modules, architectures
+```
+
+### Key Technologies
+
+- **Frontend**: Next.js 15, React 18, Material-UI Joy, Emotion (CSS-in-JS)
+- **State Management**: Zustand with localStorge/IndexedDB (single cell) persistence
+- **API Layer**: tRPC with React Query for type-safe communication
+- **Runtime**: Edge Runtime for AI operations, Node.js for data processing
+
+### Apps Architecture Pattern
+
+Each app in `/src/apps/` is a self-contained feature module:
+- Main component (`App*.tsx`)
+- Local state store (`store-app-*.ts`)
+- Feature-specific components and layouts
+- Runtime configurations
+
+Example apps: `chat/`, `call/`, `beam/`, `draw/`, `personas/`, `settings-modal/`
+
+### Modules Architecture Pattern
+
+Modules in `/src/modules/` provide reusable business logic:
+- **`aix/`** - AI communication framework for real-time streaming
+- **`beam/`** - Multi-model AI reasoning system (scatter/gather pattern)
+- **`blocks/`** - Content rendering (markdown, code, images, etc.)
+- **`llms/`** - Language model abstraction supporting 16 vendors
+
+### Key Subsystems & Their Patterns
+
+#### 1. AIX - Real-time AI Communication
+**Location**: `/src/modules/aix/`
+**Pattern**: Client-server streaming architecture with provider abstraction
+
+- **Client** → tRPC → **Server** → **AI Providers**
+- Handles streaming/non-streaming responses with batching and error recovery
+- Particle-based streaming: `AixWire_Particles` → `ContentReassembler` → `DMessage`
+- Provider-agnostic through adapter pattern (OpenAI, Anthropic, Gemini protocols)
+
+#### 3. Beam - Multi-Model Reasoning
+**Location**: `/src/modules/beam/`
+**Pattern**: Scatter/Gather for parallel AI processing
+
+- **Scatter**: Multiple models (rays) process input in parallel
+- **Gather**: Fusion algorithms combine outputs
+- Real-time UI updates via vanilla Zustand stores
+- BeamStore per conversation via ConversationHandler
+
+#### 4. Conversation Management
+**Location**: `/src/common/stores/chat/` and `/src/common/chat-overlay/`
+**Pattern**: Overlay architecture with handler per conversation
+
+- `ConversationHandler` orchestrates chat, beam, ephemerals
+- Per-chat stores: `PerChatOverlayStore` + `BeamStore`
+- Message structure: `DMessage` → `DMessageFragment[]`
+- Supports multi-pane with independent conversation states
+
+### Storage System
+
+Big-AGI uses a local-first architecture with Zustand + IndexedDB:
+- **Zustand** stores for in-memory state management
+- **localStorage** for persistent settings/all storage (via Zustand persist middleware)
+- **IndexedDB** for persistent chat-only storage (via Zustand persist middleware) on a single key-val cell
+- **Local-first** architecture with offline capability
+- **Migration system** for upgrading data structures across versions
+
+Key storage patterns:
+- Stores use `createIDBPersistStorage()` for IndexedDB persistence
+- Version-based migrations handle data structure changes
+- Partialize/merge functions control what gets persisted
+- Rehydration logic repairs and upgrades data on load
+
+Located in `/src/common/stores/` with stores like:
+- `chat/store-chats.ts`: Conversations and messages
+- `llms/store-llms.ts`: Model configurations
+
+### Layout System ("Optima")
+
+The Optima layout system provides:
+- **Responsive design** adapting desktop/mobile
+- **Drawer/Panel/Toolbar** composition
+- **Split-pane support** for multi-conversation views
+- **Portal-based rendering** for flexible component placement
+
+Located in `/src/common/layout/optima/`
+
+### State Management Patterns
+
+1. **Global Stores** (Zustand with IndexedDB persistence)
+   - `store-chats`: Conversations and messages
+   - `store-llms`: Model configurations
+   - `store-ux-labs`: UI preferences and labs features
+
+2. **Per-Instance Stores** (Vanilla Zustand)
+   - `store-beam_vanilla`: Beam scatter/gather state
+   - `store-perchat_vanilla`: Chat overlay state
+   - High-performance, no React integration
+
+3. **Module Stores**
+   - Feature-specific configuration and state
+   - Example: `store-module-beam`, `store-module-t2i`
+
+### User Flows & Interdependencies
+
+#### Chat Message Flow
+1. User input → `Composer` → `DMessage` creation
+2. `ConversationHandler.messageAppend()` → Store update
+3. `_handleExecute()` / `ConversationHandler.executeChatMessages()` → AIX client request
+4. AIX streaming → `ContentReassembler` → UI updates
+5. Zustand auto-persistence → IndexedDB
+
+#### Beam Multi-Model Flow
+1. User triggers Beam → `BeamStore.open()` state update
+2. Scatter: Parallel `aixChatGenerateContent()` to N models
+3. Real-time ray updates → UI progress
+4. Gather: User selects fusion → Combined output
+5. Result → New message in conversation
+
+### Development Patterns
+
+#### Module Integration
+- Each module exports its functionality through index files
+- Modules register with central registries (e.g., `vendors.registry.ts`)
+- Configuration objects define module behavior
+- Type-safe integration through strict TypeScript interfaces
+
+#### Component Patterns
+- **Controlled components** with clear prop interfaces
+- **Hook-based logic** extraction for reusability
+- **Portal rendering** for overlays and modals
+- **Suspense boundaries** for async operations
+
+#### API Patterns
+- **tRPC routers** for type-safe API endpoints
+- **Zod schemas** for runtime validation
+- **Middleware** for request/response processing
+- **Edge functions** for performance-critical AI operations
+
+## Security Considerations
+
+- API keys stored client-side in localStorage (user-provided)
+- Server-side API keys in environment variables only
+- XSS protection through proper content escaping
+- No credential transmission to third parties
+
+## Knowledge Base
+
+Architecture and system documentation is available in the `/kb/` knowledge base:
+
+@kb/KB.md
+
+## Common Development Tasks
+
+### Testing & Quality
+- Run `npm run lint` before committing
+- Type-check with `npx tsc --noEmit`
+- Test critical user flows manually
+
+### Adding a New LLM Vendor
+1. Create vendor in `/src/modules/llms/vendors/[vendor]/`
+2. Implement `IModelVendor` interface
+3. Register in `vendors.registry.ts`
+4. Add environment variables to `env.ts` (if server-side keys needed)
+
+### Debugging Storage Issues
+- Check IndexedDB: DevTools → Application → IndexedDB → `app-chats`
+- Monitor Zustand state: Use Zustand DevTools
+- Check migration logs in console during rehydration
+
+## Code Examples
+
+### AIX Streaming Pattern
+```typescript
+// Efficient streaming with decimation
+aixChatGenerateContent_DMessage(
+  llmId,
+  request,
+  { abortSignal, throttleParallelThreads: 1 },
+  async (update, isDone) => {
+    // Real-time UI updates
+  }
+);
+```
+
+### Model Registry Pattern
+```typescript
+// Registry pattern for extensibility
+const MODEL_VENDOR_REGISTRY: Record<ModelVendorId, IModelVendor> = {
+  openai: ModelVendorOpenAI,
+  anthropic: ModelVendorAnthropic,
+  // ... 14 more vendors
+};
+```
+
+## Server Architecture
+
+The server uses a split architecture with two tRPC routers:
+
+### Edge Network (`trpc.router-edge`)
+Distributed edge runtime for low-latency AI operations:
+- **AIX** - AI streaming and communication
+- **LLM Routers** - Direct vendor integrations (OpenAI, Anthropic, Gemini, Ollama)
+- **External Services** - ElevenLabs (TTS), Google Search, YouTube transcripts
+
+Located at `/src/server/trpc/trpc.router-edge.ts`
+
+### Cloud Network (`trpc.router-cloud`)
+Centralized server for data processing operations:
+- **Browse** - Web scraping and content extraction
+- **Trade** - Import/export functionality (ChatGPT, markdown, JSON)
+
+Located at `/src/server/trpc/trpc.router-cloud.ts`
+
+**Key Pattern**: Edge runtime for AI (fast, distributed), Cloud runtime for data ops (centralized, Node.js)

Dockerfile

@@ -1,7 +1,6 @@
 # Base
-FROM node:18-alpine AS base
-ENV NEXT_TELEMETRY_DISABLED 1
-
+FROM node:22-alpine AS base
+ENV NEXT_TELEMETRY_DISABLED=1
 
 # Dependencies
 FROM base AS deps
@@ -11,8 +10,11 @@ WORKDIR /app
 COPY package*.json ./
 COPY src/server/prisma ./src/server/prisma
 
+# link ssl3 for latest Alpine
+RUN sh -c '[ ! -e /lib/libssl.so.3 ] && ln -s /usr/lib/libssl.so.3 /lib/libssl.so.3 || echo "Link already exists"'
+
 # Install dependencies, including dev (release builds should use npm ci)
-ENV NODE_ENV development
+ENV NODE_ENV=development
 RUN npm ci
 
 
@@ -20,16 +22,32 @@ RUN npm ci
 FROM base AS builder
 WORKDIR /app
 
+# Deployment type marker
+ENV NEXT_PUBLIC_DEPLOYMENT_TYPE=docker
+
+# Optional build version arguments at build time
+ARG NEXT_PUBLIC_BUILD_HASH
+ENV NEXT_PUBLIC_BUILD_HASH=${NEXT_PUBLIC_BUILD_HASH}
+ARG NEXT_PUBLIC_BUILD_REF_NAME
+ENV NEXT_PUBLIC_BUILD_REF_NAME=${NEXT_PUBLIC_BUILD_REF_NAME}
+
 # Optional argument to configure GA4 at build time (see: docs/deploy-analytics.md)
 ARG NEXT_PUBLIC_GA4_MEASUREMENT_ID
 ENV NEXT_PUBLIC_GA4_MEASUREMENT_ID=${NEXT_PUBLIC_GA4_MEASUREMENT_ID}
 
+# Optional argument to configure PostHog at build time (see: docs/deploy-analytics.md)
+ARG NEXT_PUBLIC_POSTHOG_KEY
+ENV NEXT_PUBLIC_POSTHOG_KEY=${NEXT_PUBLIC_POSTHOG_KEY}
+
 # Copy development deps and source
 COPY --from=deps /app/node_modules ./node_modules
 COPY . .
 
+# link ssl3 for latest Alpine
+RUN sh -c '[ ! -e /lib/libssl.so.3 ] && ln -s /usr/lib/libssl.so.3 /lib/libssl.so.3 || echo "Link already exists"'
+
 # Build the application
-ENV NODE_ENV production
+ENV NODE_ENV=production
 RUN npm run build
 
 # Reduce installed packages to production-only
@@ -51,8 +69,8 @@ COPY --from=builder --chown=nextjs:nodejs /app/node_modules ./node_modules
 COPY --from=builder --chown=nextjs:nodejs /app/src/server/prisma ./src/server/prisma
 
 # Minimal ENV for production
-ENV NODE_ENV production
-ENV PATH $PATH:/app/node_modules/.bin
+ENV NODE_ENV=production
+ENV PATH=$PATH:/app/node_modules/.bin
 
 # Run as non-root user
 USER nextjs
@@ -61,4 +79,4 @@ USER nextjs
 EXPOSE 3000
 
 # Start the application
-CMD ["next", "start"]
+CMD ["next", "start"]

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2023-2024 Enrico Ros
+Copyright (c) 2023-2025 Enrico Ros
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -1,50 +1,160 @@
-# BIG-AGI 🧠✨
+# Big-AGI Open 🧠
 
-Welcome to big-AGI, the AI suite for professionals that need function, form,
-simplicity, and speed. Powered by the latest models from 12 vendors and
-open-source servers, `big-AGI` offers best-in-class Chats,
-[Beams](https://github.com/enricoros/big-AGI/issues/470),
-and [Calls](https://github.com/enricoros/big-AGI/issues/354) with AI personas,
-visualizations, coding, drawing, side-by-side chatting, and more -- all wrapped in a polished UX.
+This is the open-source foundation of **Big-AGI**, ___the multi-model AI workspace for experts___.
 
-Stay ahead of the curve with big-AGI. 🚀 Pros & Devs love big-AGI. 🤖
+Big-AGI is the multi-model AI workspace for experts: Engineers architecting systems. Founders making decisions. Researchers validating hypotheses.
+You need to think broader, decide faster, and build with confidence, then you need Big-AGI.
 
-[![Official Website](https://img.shields.io/badge/BIG--AGI.com-%23096bde?style=for-the-badge&logo=vercel&label=launch)](https://big-agi.com)
+It comes packed with **world-class features** like Beam, and is praised for its **best-in-class AI chat UX**.
+**As an independent, non-VC-funded project, Pro subscriptions at $10.99/mo fund development for everyone, including the free and open-source tiers.**
 
-Or fork & run on Vercel
+**What makes Big-AGI different:**  
+**Intelligence**: with [Beam & Merge](https://big-agi.com/beam) for multi-model de-hallucination, native search, and bleeding-edge AI models like Nano Banana, or GPT-5 Pro - 
+**Control**: with personas, data ownership, requests inspection, unlimited usage with API keys, and *no vendor lock-in* - 
+and **Speed**: with a local-first, over-powered, zero-latency, madly optimized web app.
+
+**Who uses Big-AGI:**  
+Loved by engineers, founders, researchers, self-hosters, and IT departments for its power, reliability, and transparency.
+
+<img width="830" height="370" alt="image" src="https://github.com/user-attachments/assets/513c4f77-0970-4a56-b23b-1416c8246174" />
+
+Choose Big-AGI because you don't need another clone or slop - you need an AI tool that scales with you.
+
+## Get Started
+
+| Tier                                                 | Best For          | What You Get                                                  | Setup       |
+|------------------------------------------------------|-------------------|---------------------------------------------------------------|-------------|
+| Big-AGI Open (self-host)                             | **IT**            | First to get new models support. Maximum control and privacy. | 5-30 min    |
+| [big-agi.com](https://big-agi.com) Free              | **Everyone**      | Full core experience, improved Beam, new Personas, best UX.   | **2 min**\* |
+| **[big-agi.com](https://big-agi.com) Pro** $10.99/mo | **Professionals** | Everything + **Sync** across unlimited devices + 1GB storage  | **2 min**\* |
+
+\*: **Configuration requires your API keys**. *Big-AGI does not charge for model usage or limit your access*.  
+**Why Pro?** As an independent project, Pro subscriptions fund all development. Early subscribers shape the roadmap directly.    
+
+<a href="https://big-agi.com">
+  <img width="210" height="68" alt="image" src="https://github.com/user-attachments/assets/b2f8a7b8-415f-4c92-b228-4f5a54fe2bdd" />
+</a>  
+
+**Self-host and developers** (full control)  
+- Develop locally or self-host with Docker on your own infrastructure – [guide](docs/installation.md)  
+- Or fork & run on Vercel:
 
 [![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2Fenricoros%2Fbig-AGI&env=OPENAI_API_KEY&envDescription=Backend%20API%20keys%2C%20optional%20and%20may%20be%20overridden%20by%20the%20UI.&envLink=https%3A%2F%2Fgithub.com%2Fenricoros%2Fbig-AGI%2Fblob%2Fmain%2Fdocs%2Fenvironment-variables.md&project-name=big-AGI)
 
-## 👉 [roadmap](https://github.com/users/enricoros/projects/4/views/2) 👉 [installation](docs/installation.md) 👉 [documentation](docs/README.md)
+[//]: # (**For the latest Big-AGI:**)
 
-[//]: # (big-AGI is an open book; see the **[ready-to-ship and future ideas]&#40;https://github.com/users/enricoros/projects/4/views/2&#41;** in our open roadmap)
+[//]: # (- [**Big-AGI Open**]&#40;https://github.com/enricoros/big-AGI/tree/main&#41; - Open Source, latest models and features &#40;main branch&#41;)
 
-#### What's New in 1.15.1 · April 10, 2024 (minor release, models support)
+[//]: # (- [**Big-AGI Pro**]&#40;https://big-agi.com&#41; - Hosted with Cloud Sync)
 
-- Support for the newly released Gemini Pro 1.5 models
-- Support for the new OpenAI 2024-04-09 Turbo models
-- Ctrl+S and Ctrl+O to save/load chats on desktop
-- Resilience fixes after the large success of 1.15.0
+---
 
-> Note: Beam-2 and new larger features are being cooked outside of `main`.
+## Our Philosophy
 
-### 3,000 Commits Milestone · April 7, 2024
+We're an independent, non-VC-funded project with a simple belief: **AI should elevate you, not replace you**.
+
+This is why we built Big-AGI to be **local-first**, madly optimized to 0-latency, launched multi-model first to
+defeat hallucinations, designed Beam around the **humans in the loop**, re-wrote frameworks and abstractions
+so you **are not vendor locked-in**, and obsessed over a powerful UI that works, just works.
+
+NOTE: this is a powerful tool - if you need a toy UI or clone, this ain't it.
+
+
+## What's New in 2.0 · Oct 31, 2025 · Open
+
+👉 **[See the full changelog](https://big-agi.com/changes)**
+
+- **Big-AGI Open** is ready and more productive and faster than ever, with:
+- **Beam 2**: multi-modal, program-based, follow-ups, save presets
+- Top-notch AI models support including **agentic models** and **reasoning models**
+- **Image Generation** and editing with Nano Banana and gpt-image-1
+- **Web Search** with citations for supported models
+- **UI** & Mobile UI overhaul with peeking and side panels
+- And all of the [Big-AGI 2 changes](https://github.com/enricoros/big-AGI/issues/567#issuecomment-2262187617) and more
+- Built for the future, madly optimized
+
+<img width="830" height="385" alt="image" src="https://github.com/user-attachments/assets/ad52761d-7e3f-44d8-b41e-947ce8b4faa1" />
+
+### Open links: 👉 [changelog](https://big-agi.com/changes) 👉 [installation](docs/installation.md) 👉 [roadmap](https://github.com/users/enricoros/projects/4/views/2) 👉 [documentation](docs/README.md)
+
+**For teams and institutions:** Need shared prompts, SSO, or managed deployments? Reach out at enrico@big-agi.com. We're actively collecting requirements from research groups and IT departments.
+
+<details>
+<summary>5,000 Commits Milestone</summary>
+
+Hit 5k commits last week. That's a lot of code.
+
+Recent work has been intense:
+- Chain of thought reasoning across multiple LLMs: **OpenAI o3** and o1, **DeepSeek R1**, **Gemini 2.0 Flash Thinking**, and more
+- Beam is real - ~35% of our users run it daily to compare models
+- New AIX framework lets us scale features we couldn't before
+- UI is faster than ever. Like, terminal-fast
+
+The new architecture is solid and the speed improvements are real.
+
+![5000e-830px](https://github.com/user-attachments/assets/42f7420b-9331-421b-9a18-2e653aaa7d9b)
+
+</details>
+
+<details>
+<summary>What's New in 1.16.1...1.16.10 · 2024-2025 (patch releases)</summary>
+
+- 1.16.10: OpenRouter models support
+- 1.16.9: Docker Gemini fix, R1 models support
+- 1.16.8: OpenAI ChatGPT-4o Latest, o1 models support
+- 1.16.7: OpenAI support for GPT-4o 2024-08-06
+- 1.16.6: Groq support for Llama 3.1 models
+- 1.16.5: GPT-4o Mini support
+- 1.16.4: 8192 tokens support for Claude 3.5 Sonnet
+- 1.16.3: Anthropic Claude 3.5 Sonnet model support
+- 1.16.2: Improve web downloads, as text, markdown, or HTML
+- 1.16.2: Proper support for Gemini models
+- 1.16.2: Added the latest Mistral model
+- 1.16.2: Tokenizer support for gpt-4o
+- 1.16.2: Updates to Beam
+- 1.16.1: Support for the new OpenAI GPT-4o 2024-05-13 model
+
+</details>
+
+<details>
+<summary>What's New in 1.16.0 · May 9, 2024 · Crystal Clear</summary>
+
+- [Beam](https://big-agi.com/blog/beam-multi-model-ai-reasoning) core and UX improvements based on user feedback
+- Chat cost estimation 💰 (enable it in Labs / hover the token counter)
+- Save/load chat files with Ctrl+S / Ctrl+O on desktop
+- Major enhancements to the Auto-Diagrams tool
+- YouTube Transcriber Persona for chatting with video content, [#500](https://github.com/enricoros/big-AGI/pull/500)
+- Improved formula rendering (LaTeX), and dark-mode diagrams, [#508](https://github.com/enricoros/big-AGI/issues/508), [#520](https://github.com/enricoros/big-AGI/issues/520)
+- Models update: **Anthropic**, **Groq**, **Ollama**, **OpenAI**, **OpenRouter**, **Perplexity**
+- Code soft-wrap, chat text selection toolbar, 3x faster on Apple silicon, and more [#517](https://github.com/enricoros/big-AGI/issues/517), [507](https://github.com/enricoros/big-AGI/pull/507)
+
+</details>
+
+<details>
+<summary>3,000 Commits Milestone · April 7, 2024</summary>
 
 ![big-AGI Milestone](https://github.com/enricoros/big-AGI/assets/32999/47fddbb1-9bd6-4b58-ace4-781dfcb80923)
 
 - 🥇 Today we <b>celebrate commit 3000</b> in just over one year, and going stronger 🚀
 - 📢️ Thanks everyone for your support and words of love for Big-AGI, we are committed to creating the best AI experiences for everyone.
 
-### What's New in 1.15.0 · April 1, 2024 · Beam
+</details>
+
+<details>
+<summary>What's New in 1.15.0 · April 1, 2024 · Beam</summary>
 
 - ⚠️ [**Beam**: the multi-model AI chat](https://big-agi.com/blog/beam-multi-model-ai-reasoning). find better answers, faster - a game-changer for brainstorming, decision-making, and creativity. [#443](https://github.com/enricoros/big-AGI/issues/443)
 - Managed Deployments **Auto-Configuration**: simplify the UI models setup with backend-set models. [#436](https://github.com/enricoros/big-AGI/issues/436)
 - Message **Starring ⭐**: star important messages within chats, to attach them later. [#476](https://github.com/enricoros/big-AGI/issues/476)
 - Enhanced the default Persona
 - Fixes to Gemini models and SVGs, improvements to UI and icons
+- 1.15.1: Support for Gemini Pro 1.5 and OpenAI Turbo models
 - Beast release, over 430 commits, 10,000+ lines changed: [release notes](https://github.com/enricoros/big-AGI/releases/tag/v1.15.0), and changes [v1.14.1...v1.15.0](https://github.com/enricoros/big-AGI/compare/v1.14.1...v1.15.0)
 
-### What's New in 1.14.1 · March 7, 2024 · Modelmorphic
+</details>
+
+<details>
+<summary>What's New in 1.14.1 · March 7, 2024 · Modelmorphic</summary>
 
 - **Anthropic** [Claude-3](https://www.anthropic.com/news/claude-3-family) model family support. [#443](https://github.com/enricoros/big-AGI/issues/443)
 - New **[Perplexity](https://www.perplexity.ai/)** and **[Groq](https://groq.com/)** integration (thanks @Penagwin). [#407](https://github.com/enricoros/big-AGI/issues/407), [#427](https://github.com/enricoros/big-AGI/issues/427)
@@ -54,7 +164,10 @@ Or fork & run on Vercel
 - Enhanced UX with auto-sizing charts, refined search and folder functionalities, perfected scaling
 - And with more UI improvements, documentation, bug fixes (20 tickets), and developer enhancements
 
-### What's New in 1.13.0 · Feb 8, 2024 · Multi + Mind
+</details>
+
+<details>
+<summary>What's New in 1.13.0 · Feb 8, 2024 · Multi + Mind</summary>
 
 https://github.com/enricoros/big-AGI/assets/32999/01732528-730e-41dc-adc7-511385686b13
 
@@ -66,6 +179,8 @@ https://github.com/enricoros/big-AGI/assets/32999/01732528-730e-41dc-adc7-511385
 - Better looking chats with improved spacing, fonts, and menus
 - More: new video player, [LM Studio tutorial](https://github.com/enricoros/big-AGI/blob/main/docs/config-local-lmstudio.md) (thanks @aj47), [MongoDB support](https://github.com/enricoros/big-AGI/blob/main/docs/deploy-database.md) (thanks @ranfysvalle02), and speedups
 
+</details>
+
 <details>
 <summary>What's New in 1.12.0 · Jan 26, 2024 · AGI Hotline</summary>
 
@@ -108,9 +223,9 @@ https://github.com/enricoros/big-AGI/assets/1590910/a6b8e172-0726-4b03-a5e5-10cf
 
 </details>
 
-For full details and former releases, check out the [changelog](docs/changelog.md).
+For full details and former releases, check out the [archived versions changelog](docs/changelog.md).
 
-## 👉 Key Features ✨
+## 👉 Key Features
 
 | ![Advanced AI](https://img.shields.io/badge/Advanced%20AI-32383e?style=for-the-badge&logo=ai&logoColor=white) | ![100+ AI Models](https://img.shields.io/badge/100%2B%20AI%20Models-32383e?style=for-the-badge&logo=ai&logoColor=white) | ![Flow-state UX](https://img.shields.io/badge/Flow--state%20UX-32383e?style=for-the-badge&logo=flow&logoColor=white) | ![Privacy First](https://img.shields.io/badge/Privacy%20First-32383e?style=for-the-badge&logo=privacy&logoColor=white) | ![Advanced Tools](https://img.shields.io/badge/Fun%20To%20Use-f22a85?style=for-the-badge&logo=tools&logoColor=white) |  
 |---------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------| 
@@ -120,14 +235,14 @@ For full details and former releases, check out the [changelog](docs/changelog.m
 
 You can easily configure 100s of AI models in big-AGI:
 
-| **AI models**       | _supported vendors_                                                                                                                                                                                                             |
-|:--------------------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| Opensource Servers  | [LocalAI](https://localai.com) (multimodal) · [Ollama](https://ollama.com/) · [Oobabooga](https://github.com/oobabooga/text-generation-webui)                                                                                   |
-| Local Servers       | [LM Studio](https://lmstudio.ai/)                                                                                                                                                                                               |
-| Multimodal services | [Azure](https://azure.microsoft.com/en-us/products/ai-services/openai-service) · [Google Gemini](https://ai.google.dev/) · [OpenAI](https://platform.openai.com/docs/overview)                                                  |
-| Language services   | [Anthropic](https://anthropic.com) · [Groq](https://wow.groq.com/) · [Mistral](https://mistral.ai/) · [OpenRouter](https://openrouter.ai/) · [Perplexity](https://www.perplexity.ai/) · [Together AI](https://www.together.ai/) | 
-| Image services      | [Prodia](https://prodia.com/) (SDXL)                                                                                                                                                                                            | 
-| Speech services     | [ElevenLabs](https://elevenlabs.io) (Voice synthesis / cloning)                                                                                                                                                                 | 
+| **AI models**       | _supported vendors_                                                                                                                                                                                                                                                                                               |
+|:--------------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| Opensource Servers  | [LocalAI](https://localai.io/) (multimodal) · [Ollama](https://ollama.com/)                                                                                                                                                                                                                                       |
+| Local Servers       | [LM Studio](https://lmstudio.ai/)                                                                                                                                                                                                                                                                                 |
+| Multimodal services | [Azure](https://azure.microsoft.com/en-us/products/ai-services/openai-service) · [Anthropic](https://anthropic.com) · [Google Gemini](https://ai.google.dev/) · [OpenAI](https://platform.openai.com/docs/overview)                                                                                               |
+| Language services   | [Alibaba](https://www.alibabacloud.com/en/product/modelstudio) · [DeepSeek](https://deepseek.com) · [Groq](https://wow.groq.com/) · [Mistral](https://mistral.ai/) · [OpenRouter](https://openrouter.ai/) · [Perplexity](https://www.perplexity.ai/) · [Together AI](https://www.together.ai/) · [xAI](https://x.ai/) |
+| Image services      | OpenAI · Google Gemini                                                                                                                                                                                                                                                                                            |
+| Speech services     | [ElevenLabs](https://elevenlabs.io) (Voice synthesis / cloning)                                                                                                                                                                                                                                                   | 
 
 Add extra functionality with these integrations:
 
@@ -136,7 +251,6 @@ Add extra functionality with these integrations:
 | Web Browse   | [Browserless](https://www.browserless.io/) · [Puppeteer](https://pptr.dev/)-based                              |
 | Web Search   | [Google CSE](https://programmablesearchengine.google.com/)                                                     |
 | Code Editors | [CodePen](https://codepen.io/pen/) · [StackBlitz](https://stackblitz.com/) · [JSFiddle](https://jsfiddle.net/) |
-| Sharing      | [Paste.gg](https://paste.gg/) (Paste chats)                                                                    | 
 | Tracking     | [Helicone](https://www.helicone.ai) (LLM Observability)                                                        | 
 
 [//]: # (- [x] **Flow-state UX** for uncompromised productivity)
@@ -194,6 +308,13 @@ Or bring your API keys and jump straight into our free instance on [big-AGI.com]
 
 [//]: # ([![License]&#40;https://img.shields.io/github/license/enricoros/big-agi&#41;]&#40;https://github.com/enricoros/big-agi/LICENSE&#41;)
 
+## 📜 Licensing
+
+Big-AGI incorporates third-party software components that are subject
+to separate license terms. For detailed information about these
+components and their respective licenses, please refer to
+the [Third-Party Notices](src/modules/3rdparty/THIRD_PARTY_NOTICES.md).
+
 ---
 
-2023-2024 · Enrico Ros x [big-AGI](https://big-agi.com) · License: [MIT](LICENSE) · Made with 💙
+2023-2025 · Enrico Ros x [Big-AGI](https://big-agi.com) · Like this project? Leave a star! 💫⭐

app/api/cloud/[trpc]/route.ts

@@ -0,0 +1,39 @@
+import { fetchRequestHandler } from '@trpc/server/adapters/fetch';
+
+import { appRouterCloud } from '~/server/trpc/trpc.router-cloud';
+import { createTRPCFetchContext } from '~/server/trpc/trpc.server';
+import { posthogCaptureServerException } from '~/server/posthog/posthog.server';
+
+const handlerNodeRoutes = (req: Request) => fetchRequestHandler({
+  endpoint: '/api/cloud',
+  router: appRouterCloud,
+  req,
+  createContext: createTRPCFetchContext,
+  onError: async function({ path, error, type, ctx }) {
+
+    // -> DEV error logging
+    if (process.env.NODE_ENV === 'development')
+      console.error(`❌ tRPC-cloud failed on ${path ?? 'unk-path'}: ${error.message}`);
+
+    // -> Capture node errors
+    await posthogCaptureServerException(error, {
+      domain: 'trpc-onerror',
+      runtime: 'nodejs',
+      endpoint: path ?? 'unknown',
+      method: req.method,
+      url: req.url,
+      additionalProperties: {
+        errorCode: error.code,
+        errorType: type,
+      },
+    });
+  },
+});
+
+
+// NOTE: the following statement breaks the build on non-pro deployments, and conditionals don't work either
+//       so we resorted to raising the timeout from 10s to 60s in the vercel.json file instead
+export const maxDuration = 60;
+export const runtime = 'nodejs';
+export const dynamic = 'force-dynamic';
+export { handlerNodeRoutes as GET, handlerNodeRoutes as POST };

app/api/edge/[trpc]/route.ts

@@ -0,0 +1,18 @@
+import { fetchRequestHandler } from '@trpc/server/adapters/fetch';
+
+import { appRouterEdge } from '~/server/trpc/trpc.router-edge';
+import { createTRPCFetchContext } from '~/server/trpc/trpc.server';
+
+const handlerEdgeRoutes = (req: Request) => fetchRequestHandler({
+  endpoint: '/api/edge',
+  router: appRouterEdge,
+  req,
+  createContext: createTRPCFetchContext,
+  onError:
+    process.env.NODE_ENV === 'development'
+      ? ({ path, error }) => console.error(`❌ tRPC-edge failed on ${path ?? 'unk-path'}: ${error.message}`)
+      : undefined,
+});
+
+export const runtime = 'edge';
+export { handlerEdgeRoutes as GET, handlerEdgeRoutes as POST };

app/api/elevenlabs/speech/route.ts

@@ -1,2 +0,0 @@
-export const runtime = 'edge';
-export { elevenLabsHandler as POST } from '~/modules/elevenlabs/elevenlabs.server';

app/api/llms/stream/route.ts

@@ -1,2 +0,0 @@
-export const runtime = 'edge';
-export { llmStreamingRelayHandler as POST } from '~/modules/llms/server/llm.server.streaming';

app/api/trpc-edge/[trpc]/route.ts

@@ -1,19 +0,0 @@
-import { fetchRequestHandler } from '@trpc/server/adapters/fetch';
-
-import { appRouterEdge } from '~/server/api/trpc.router-edge';
-import { createTRPCFetchContext } from '~/server/api/trpc.server';
-
-const handlerEdgeRoutes = (req: Request) =>
-  fetchRequestHandler({
-    router: appRouterEdge,
-    endpoint: '/api/trpc-edge',
-    req,
-    createContext: createTRPCFetchContext,
-    onError:
-      process.env.NODE_ENV === 'development'
-        ? ({ path, error }) => console.error(`❌ tRPC-edge failed on ${path ?? "<no-path>"}: ${error.message}`)
-        : undefined,
-  });
-
-export const runtime = 'edge';
-export { handlerEdgeRoutes as GET, handlerEdgeRoutes as POST };

app/api/trpc-node/[trpc]/route.ts

@@ -1,23 +0,0 @@
-import { fetchRequestHandler } from '@trpc/server/adapters/fetch';
-
-import { appRouterNode } from '~/server/api/trpc.router-node';
-import { createTRPCFetchContext } from '~/server/api/trpc.server';
-
-const handlerNodeRoutes = (req: Request) =>
-  fetchRequestHandler({
-    router: appRouterNode,
-    endpoint: '/api/trpc-node',
-    req,
-    createContext: createTRPCFetchContext,
-    onError:
-      process.env.NODE_ENV === 'development'
-        ? ({ path, error }) => console.error(`❌ tRPC-node failed on ${path ?? '<no-path>'}: ${error.message}`)
-        : undefined,
-  });
-
-export const runtime = 'nodejs';
-// NOTE: the following statement breaks the build on non-pro deployments, and conditionals don't work either
-//       so we resorted to raising the timeout from 10s to 25s in the vercel.json file instead
-// export const maxDuration = 25;
-export const dynamic = 'force-dynamic';
-export { handlerNodeRoutes as GET, handlerNodeRoutes as POST };

docker-compose.yaml

@@ -1,6 +1,6 @@
 # Very simple docker-compose file to run the app on http://localhost:3000 (or http://127.0.0.1:3000).
 #
-# For more examples, such runnin big-AGI alongside a web browsing service, see the `docs/docker` folder.
+# For more examples, such running big-AGI alongside a web browsing service, see the `docs/docker` folder.
 
 version: '3.9'
 

docs/2024-AI-APIs-Comparison.md

@@ -0,0 +1,70 @@
+# AIX dispatch server - API features comparison
+
+This is updated as of 2024-07-09, and includes the latest features and capabilities of the three major AI APIs: Anthropic, Gemini, and OpenAI.
+The comparison covers a wide range of features, including function calling, vision, system instructions, etc.
+
+| Feature Category                         | Specific Feature              | Anthropic                                                          | Gemini                                                           | OpenAI                                                              |
+|------------------------------------------|-------------------------------|--------------------------------------------------------------------|------------------------------------------------------------------|---------------------------------------------------------------------|
+| **Message Structure**                    |
+|                                          | Role types                    | user, assistant                                                    | user, model                                                      | user, assistant, system, tool                                       |
+|                                          | Named participants            | No                                                                 | No                                                               | Yes                                                                 |
+|                                          | Content array                 | Yes                                                                | Yes                                                              | Yes                                                                 |
+| **Content Types and Multimodal Support** |
+|                                          | Text generation               | Yes                                                                | Yes                                                              | Yes                                                                 |
+|                                          | Image understanding           | Yes                                                                | Yes                                                              | Yes                                                                 |
+|                                          | Audio processing              | No                                                                 | **Yes**                                                          | No                                                                  |
+|                                          | Video processing              | No                                                                 | **Yes**                                                          | No                                                                  |
+| **Image Handling**                       |
+|                                          | Supported formats             | JPEG, PNG, GIF, WebP                                               | JPEG, PNG, WebP, HEIC, HEIF                                      | PNG, JPEG, WebP, non-animated GIF                                   |
+|                                          | Max image size                | 5MB per image                                                      | (20MB per prompt)                                                | 20MB per image                                                      |
+|                                          | Image detail level            | N/A                                                                | N/A                                                              | **Low, high, auto**                                                 |
+|                                          | Image resolution              | max: 1568x1568                                                     | min: 768x768, max: 3072x3072                                     | min: 512x512, max: 2048 x 2048                                      |
+|                                          | Token calculation for images  | (width * height)/750; max 1,600                                    | 258 tokens                                                       | 85 + 170 * {patches}                                                |
+|                                          | Image retention               | Deleted after processing                                           | Not specified                                                    | Deleted after processing                                            |
+| **Audio and Video Handling**             |
+|                                          | Audio formats                 | N/A                                                                | WAV, MP3, AIFF, AAC, OGG, FLAC                                   | N/A                                                                 |
+|                                          | Video formats                 | N/A                                                                | MP4, MPEG, MOV, AVI, MPG, WebM, WMV, 3GPP                        | N/A                                                                 |
+| **System Instructions and Tool Use**     |
+|                                          | System instructions           | Yes (array of text blocks)                                         | Yes (parts array)                                                | Yes (as system message)                                             |
+| **Function/Tool Handling**               |
+|                                          | Parallel tool calls           | No                                                                 | No                                                               | **Yes**                                                             |
+|                                          | Tool Declaration              | Defined in `tools` array                                           | Defined in `tools` array                                         | Defined in `tools` array                                            |
+|                                          | FC name restrictions          | Yes                                                                | Yes (max 63 chars)                                               | Yes (max 64 chars)                                                  |
+|                                          | FC declaration                | name, description, input_schema                                    | name, description, parameters                                    | name, description, parameters                                       |
+|                                          | FC options structure          | JSON Schema for input                                              | Object with properties                                           | JSON Schema for parameters                                          |
+|                                          | FC Force invocation           | Via `tool_choice` parameter                                        | Via `toolConfig` parameter                                       | Via `tool_choice` parameter                                         |
+|                                          | FC Model invocation           | Model generates a `tool_use` block with predicted parameters       | Generates a `functionCall` part with predicted parameters        | Generates a message.`tool_calls` item with predicted arguments      |
+|                                          | FC Execution                  | Client-side                                                        | Client-side                                                      | Client-side                                                         |
+|                                          | FC Result injection           | Client appends a `user` message with a `tool_result` content block | Client appends a `function` message with `functionResponse` part | Client sends a new `tool` message with `tool_call_id` and `content` |
+|                                          | Built-in Code execution       | No                                                                 | **Yes**                                                          | No                                                                  |
+|                                          | Tool use with vision          | Yes                                                                | Yes                                                              | Yes                                                                 |
+| **Generation Configuration**             |
+|                                          | temperature                   | Yes                                                                | Yes                                                              | Yes                                                                 |
+|                                          | max_tokens                    | Yes                                                                | Yes                                                              | Yes                                                                 |
+|                                          | stop_sequences                | Yes                                                                | Yes                                                              | Yes                                                                 |
+|                                          | top_k                         | Yes                                                                | Yes                                                              | **No**                                                              |
+|                                          | top_p                         | Yes                                                                | Yes                                                              | Yes                                                                 |
+|                                          | seed                          | No                                                                 | No                                                               | **Yes**                                                             |
+|                                          | Multiple candidates           | No                                                                 | No                                                               | Yes (with 'n' parameter, breaks streaming?)                         |
+| **Streaming and Response Structure**     |
+|                                          | Streaming support             | Yes                                                                | Yes                                                              | Yes                                                                 |
+|                                          | Streaming initiation          | stream=true                                                        | streamGenerateContent path                                       | stream=true                                                         |
+|                                          | Streaming event types         | **Multiple specific types**                                        | Not specified                                                    | Single delta type                                                   |
+|                                          | Response container            | content (array)                                                    | candidates (array)                                               | choices (array)                                                     |
+| **Usage Metrics and Error Handling**     |
+|                                          | Token counts                  | Yes                                                                | Yes                                                              | Yes                                                                 |
+|                                          | Detailed token breakdown      | input, output                                                      | prompt, cached, candidates, total                                | prompt, completion, total                                           |
+|                                          | Usage in stream               | No                                                                 | No                                                               | **Optional**                                                        |
+|                                          | Error handling in response    | Not specified                                                      | Not specified                                                    | **Yes (undocumented)**                                              |
+|                                          | Error handling in stream      | Not specified                                                      | Not specified                                                    | **Yes (undocumented)**                                              |
+| **Advanced Features**                    |
+|                                          | JSON mode                     | **Partial (via structured prompts)**                               | **Yes (responseMimeType)**                                       | **Yes**                                                             |
+|                                          | Output consistency techniques | **Yes (multiple methods)**                                         | Not specified                                                    | Not specified                                                       |
+|                                          | Logprobs                      | No                                                                 | No                                                               | **Yes (disabled in schema)**                                        |
+|                                          | System fingerprint            | No                                                                 | No                                                               | **Yes**                                                             |
+|                                          | Semantic caching              | No                                                                 | **Yes**                                                          | No                                                                  |
+|                                          | Assistant prefill             | **Yes**                                                            | No                                                               | No                                                                  |
+|                                          | Preferred formatting          | **XML tags, JSON**                                                 | Not specified                                                    | Markdown                                                            |
+| **Safety and Compliance**                |
+|                                          | Safety settings in request    | **Stop sequences**                                                 | **Detailed category-based**                                      | **Moderation API**                                                  |
+|                                          | Safety feedback in response   | Yes                                                                | Yes                                                              | Not specified                                                       |

docs/README.md

@@ -1,59 +1,73 @@
-# big-AGI Documentation
+# Big-AGI Documentation
 
-Find all the information you need to get started, configure, and effectively use big-AGI.
+Information you need to get started, configure, and use big-AGI productively.
 
-[//]: # (## Quick Start)
+👉 **[Changelog](https://big-agi.com/changes)** - See what's new
 
-[//]: # (- **[Introduction](big-agi.md)**: Overview of big-AGI's features.)
+## Getting Started
 
-## Configuration Guides
+Essential guides:
 
-Detailed guides to configure your big-AGI interface and models.
+- **[FAQ](help-faq.md)**: Common questions and answers
+- **[Enabling Microphone](help-feature-microphone.md)**: Configure speech recognition in your browser
 
-👉 The following applies to the users of big-AGI.com, as the public instance is empty and to be configured by the user.
+## AI Services
 
-- **Cloud Model Services**:
-  - **[Azure OpenAI](config-azure-openai.md)**
-  - **[OpenRouter](config-openrouter.md)**
-  - easy API key: **Anthropic**, **Google AI**, **Groq**, **Mistral**, **OpenAI**, **Perplexity**, **TogetherAI**
+How to set up AI models and features in big-AGI.
+
+> 👉 The following applies to users of big-AGI.com, as the public instance is empty and requires user configuration.
+
+- **Cloud AI Services**:
+  - Easy API key configuration:
+    [Alibaba](https://bailian.console.alibabacloud.com/?apiKey=1#/api-key),
+    [Anthropic](https://console.anthropic.com/settings/keys),
+    [Deepseek](https://platform.deepseek.com/api_keys),
+    [Google Gemini](https://aistudio.google.com/app/apikey),
+    [Groq](https://console.groq.com/keys),
+    [Mistral](https://console.mistral.ai/api-keys/),
+    [OpenAI](https://platform.openai.com/api-keys),
+    [OpenPipe](https://app.openpipe.ai/settings),
+    [Perplexity](https://www.perplexity.ai/settings/api),
+    [TogetherAI](https://api.together.xyz/settings/api-keys),
+    [xAI](http://x.ai/api)
+  - **[Azure OpenAI](config-azure-openai.md)** guide
+  - **FireworksAI** ([API keys](https://fireworks.ai/account/api-keys), via custom OpenAI endpoint: https://api.fireworks.ai/inference)
+  - **[OpenRouter](config-openrouter.md)** guide
 
 
-- **Local Model Servers**:
-  - **[LocalAI](config-local-localai.md)**
-  - **[LM Studio](config-local-lmstudio.md)**
-  - **[Ollama](config-local-ollama.md)**
-  - **[Oobabooga](config-local-oobabooga.md)**
+- **Local AI Integrations**:
+  - [LocalAI](config-local-localai.md), [LM Studio](config-local-lmstudio.md), [Ollama](config-local-ollama.md)
 
 
-- **Advanced Feature Configuration**:
-  - **[Browse](config-feature-browse.md)**: Enable web page download through third-party services or your own cloud (advanced)
-  - **ElevenLabs API**: Voice and cutom voice generation, only requires their API key
-  - **Google Search API**: guide not yet available, see the Google options in '[Environment Variables](environment-variables.md)'
-  - **Prodia API**: Stable Diffusion XL image generation, only requires their API key, alternative to DALL·E
+- **Enhanced AI Features**:
+  - **[Web Browsing](config-feature-browse.md)**: Enable web page download through third-party services or your own cloud
+  - **Web Search**: Google Search API (see '[Environment Variables](environment-variables.md)')
+  - **Image Generation**: GPT Image (gpt-image-1), DALL·E 3 and 2
+  - **Voice Synthesis**: ElevenLabs API for voice generation
 
-## Deployment
+## Deployment & Customization
 
-System integrators, administrators, whitelabelers: instead of using the public big-AGI instance on get.big-agi.com, you can deploy your own instance.
+> 👉 The following applies to developers and experts who deploy their own big-AGI instance.
 
-Step-by-step deployment and system configuration instructions.
+For deploying a custom big-AGI instance:
 
-- **[Installation](installation.md)**: Set up your own instance of big-AGI and related products
-  - build from source or use pre-built
-  - locally, in the public cloud, or on your own servers
+- **[Installation Guide](installation.md)**, including:
+  - Set up your own big-AGI instance
+  - Source build or pre-built options
+  - Local, cloud, or on-premises deployment
 
 
-- **Advanced Customizations**:
-  - **[Source code alterations guide](customizations.md)**: source code primer and alterations guidelines
-  - **[Basic Authentication](deploy-authentication.md)**: Optional, adds a username and password wall
+- **Advanced Setup**:
+  - **[Source Code Customization](customizations.md)**: Modify the source code
+  - **[Access Control](deploy-authentication.md)**: Optional, add basic user authentication
   - **[Database Setup](deploy-database.md)**: Optional, enables "Chat Link Sharing"
-  - **[Environment Variables](environment-variables.md)**: 📌 Pre-configures models and services
+  - **[Reverse Proxy](deploy-reverse-proxy.md)**: Optional, enables custom domains and SSL
+  - **[Environment Variables](environment-variables.md)**: Pre-configures models and services
 
-## Support and Community
-
-Join our community or get support:
+## Community & Support
 
+- Check the [changelog](https://big-agi.com/changes) for the latest updates
 - Visit our [GitHub repository](https://github.com/enricoros/big-AGI) for source code and issue tracking
-- Check the latest updates and features on [Changelog](changelog.md) or the in-app [News](https://get.big-agi.com/news)
-- Connect with us and other users on [Discord](https://discord.gg/MkH4qj2Jp9) for discussions, help, and sharing your experiences with big-AGI
+- Join our [Discord](https://discord.gg/MkH4qj2Jp9) for discussions and help
 
-Thank you for choosing big-AGI. We're excited to see what you'll build.
+Let's build something great.

docs/changelog.md

@@ -1,19 +1,64 @@
-## Changelog
+## Archived Versions - Changelog
 
 This is a high-level changelog. Calls out some of the high level features batched
 by release.
 
+- For the live changelog, see [big-agi.com/changes](https://big-agi.com/changes)
 - For the live roadmap, please see [the GitHub project](https://github.com/users/enricoros/projects/4/views/2)
 
-### 1.16.0 - Mar 2024
+> NOTE: with the release of 2.0.0 we switching to [big-agi.com/changes](https://big-agi.com/changes) for the
+> continuously updated changelog.
 
-- milestone: [1.16.0](https://github.com/enricoros/big-agi/milestone/16)
-- work in progress: [big-AGI open roadmap](https://github.com/users/enricoros/projects/4/views/2), [help here](https://github.com/users/enricoros/projects/4/views/4)
+### What's New in 2 · Oct 31, 2025 · Open
+
+- **Big-AGI Open** is ready and more productive and faster than ever, with:
+- **Beam 2**: multi-modal, program-based, follow-ups, save presets
+- Top-notch AI models support including **agentic models** and **reasoning models**
+- **Image Generation** and editing with Nano Banana and gpt-image-1
+- **Web Search** with citations for supported models
+- **UI** & Mobile UI overhaul with peeking and side panels
+- And all of the [Big-AGI 2 changes](https://github.com/enricoros/big-AGI/issues/567#issuecomment-2262187617) and more
+- Built for the future, madly optimized
+
+### What's New in 1.16.1...1.16.9 · Jan 21, 2025 (patch releases)
+
+- 1.16.10: OpenRouter models support
+- 1.16.9: Docker Gemini fix, R1 models support
+- 1.16.8: OpenAI ChatGPT-4o Latest, o1 models support
+- 1.16.7: OpenAI support for GPT-4o 2024-08-06
+- 1.16.6: Groq support for Llama 3.1 models
+- 1.16.5: GPT-4o Mini support
+- 1.16.4: 8192 tokens support for Claude 3.5 Sonnet
+- 1.16.3: Anthropic Claude 3.5 Sonnet model support
+- 1.16.2: Improve web downloads, as text, markdown, or HTML
+- 1.16.2: Proper support for Gemini models
+- 1.16.2: Added the latest Mistral model
+- 1.16.2: Tokenizer support for gpt-4o
+- 1.16.2: Updates to Beam
+- 1.16.1: Support for the new OpenAI GPT-4o 2024-05-13 model
+
+### What's New in 1.16.0 · May 9, 2024 · Crystal Clear
+
+- [Beam](https://big-agi.com/blog/beam-multi-model-ai-reasoning) core and UX improvements based on user feedback
+- Chat cost estimation 💰 (enable it in Labs / hover the token counter)
+- Save/load chat files with Ctrl+S / Ctrl+O on desktop
+- Major enhancements to the Auto-Diagrams tool
+- YouTube Transcriber Persona for chatting with video content, [#500](https://github.com/enricoros/big-AGI/pull/500)
+- Improved formula rendering (LaTeX), and dark-mode diagrams, [#508](https://github.com/enricoros/big-AGI/issues/508), [#520](https://github.com/enricoros/big-AGI/issues/520)
+- Models update: **Anthropic**, **Groq**, **Ollama**, **OpenAI**, **OpenRouter**, **Perplexity**
+- Code soft-wrap, chat text selection toolbar, 3x faster on Apple silicon, and more [#517](https://github.com/enricoros/big-AGI/issues/517), [507](https://github.com/enricoros/big-AGI/pull/507)
+- Developers: update the LLMs data structures
+
+### What's New in 1.15.1 · April 10, 2024 (minor release, models support)
+
+- Support for the newly released Gemini Pro 1.5 models
+- Support for the new OpenAI 2024-04-09 Turbo models
+- Resilience fixes after the large success of 1.15.0
 
 ### What's New in 1.15.0 · April 1, 2024 · Beam
 
 - ⚠️ [**Beam**: the multi-model AI chat](https://big-agi.com/blog/beam-multi-model-ai-reasoning). find better answers, faster - a game-changer for brainstorming, decision-making, and creativity. [#443](https://github.com/enricoros/big-AGI/issues/443)
-- Managed Deployments **Auto-Configuration**: simplify the UI mdoels setup with backend-set models. [#436](https://github.com/enricoros/big-AGI/issues/436)
+- Managed Deployments **Auto-Configuration**: simplify the UI models setup with backend-set models. [#436](https://github.com/enricoros/big-AGI/issues/436)
 - Message **Starring ⭐**: star important messages within chats, to attach them later. [#476](https://github.com/enricoros/big-AGI/issues/476)
 - Enhanced the default Persona
 - Fixes to Gemini models and SVGs, improvements to UI and icons
@@ -105,7 +150,7 @@ https://github.com/enricoros/big-AGI/assets/1590910/a6b8e172-0726-4b03-a5e5-10cf
 - **Overheat LLMs**: Push the creativity with higher LLM temperatures. [#256](https://github.com/enricoros/big-agi/issues/256)
 - **Model Options Shortcut**: Quick adjust with `Ctrl+Shift+O`
 - Optimized Voice Input and Performance
-- Latest Ollama and Oobabooga models
+- Latest Ollama models
 - For developers: **Password Protection**: HTTP Basic Auth. [Learn How](https://github.com/enricoros/big-agi/blob/main/docs/deploy-authentication.md)
 
 ### What's New in 1.6.0 - Nov 28, 2023 · Surf's Up
@@ -137,7 +182,7 @@ For Developers:
   first request to get the configuration. See
   https://github.com/enricoros/big-agi/blob/main/src/modules/backend/backend.router.ts.
 - CloudFlare developers: please change the deployment command to
-  `rm app/api/trpc-node/[trpc]/route.ts && npx @cloudflare/next-on-pages@1`,
+  `rm app/api/cloud/[trpc]/route.ts && npx @cloudflare/next-on-pages@1`,
   as we transitioned to the App router in NextJS 14. The documentation in
   [docs/deploy-cloudflare.md](../docs/deploy-cloudflare.md) is updated
 
@@ -154,7 +199,6 @@ For Developers:
 - **Camera OCR** - real-world AI - take a picture of a text, and chat with it
 - **Anthropic models** support, e.g. Claude
 - **Backup/Restore** - save chats, and restore them later
-- **[Local model support with Oobabooga server](../docs/config-local-oobabooga)** - run your own LLMs!
 - **Flatten conversations** - conversations summarizer with 4 modes
 - **Fork conversations** - create a new chat, to try with different endings
 - New commands: /s to add a System message, and /a for an Assistant message

docs/config-azure-openai.md

@@ -14,7 +14,7 @@ If you have an `API Endpoint` and `API Key`, you can configure big-AGI as follow
 1. Launch the `big-AGI` application
 2. Go to the **Models** settings
 3. Add a Vendor and select **Azure OpenAI**
-    - Enter the Endpoint (e.g., 'https://your-openai-api-1234.openai.azure.com/')
+    - Enter the Endpoint (e.g., 'https://your-resource-name.openai.azure.com')
     - Enter the API Key (e.g., 'fd5...........................ba')
 
 The deployed models are now available in the application. If you don't have a configured
@@ -23,6 +23,36 @@ Azure OpenAI service instance, continue with the next section.
 In addition to using the UI, configuration can also be done using
 [environment variables](environment-variables.md).
 
+## Server Configuration
+
+For server deployments, set these environment variables:
+
+```bash
+AZURE_OPENAI_API_ENDPOINT=https://your-resource-name.openai.azure.com
+AZURE_OPENAI_API_KEY=your-api-key
+```
+
+This enables Azure OpenAI for all users without requiring individual API keys. For more details, see [environment-variables.md](environment-variables.md).
+
+## Azure OpenAI API Versions
+
+Azure OpenAI supports both traditional deployment-based API and the next-generation v1 API:
+
+### Next-Generation v1 API (Default)
+- **Enabled by default** for GPT-5-like models (GPT-5, GPT-6, o3, o4, etc.)
+- Uses direct `/openai/v1/responses` endpoint without deployment IDs
+- Optimized for advanced reasoning models and new features
+- Can be disabled by setting `AZURE_OPENAI_DISABLE_V1=true`
+
+### Traditional Deployment-Based API
+- Uses `/openai/deployments/{deployment-name}/...` endpoints
+- Required for older models and when v1 API is disabled
+- Needs deployment ID for all API calls
+
+### Known Limitations
+- **Web Search Tool**: Azure OpenAI does not support the `web_search_preview` tool that's available in OpenAI's API
+- Models with web search capabilities will have this feature automatically disabled on Azure
+
 ## Setting Up Azure
 
 ### Step 1: Azure Account & Subscription
@@ -34,18 +64,7 @@ In addition to using the UI, configuration can also be done using
     - Fill in the required fields and click on **Create**
     - Note down the **Subscription ID** (e.g., `12345678-1234-1234-1234-123456789012`)
 
-### Step 2: Apply for Azure OpenAI Service
-
-We'll now be creating "OpenAI"-specific resources on Azure. This requires to 'apply',
-and acceptance should be quick (even as low as minutes).
-
-1. Visit [Azure OpenAI Service](https://aka.ms/azure-openai)
-2. Click on **Apply for access**
-    - Fill in the required fields (including the subscription ID) and click on **Apply**
-
-Once your application is accepted, you can create OpenAI resources on Azure.
-
-### Step 3: Create Azure OpenAI Resource
+### Step 2: Create Azure OpenAI Resource
 
 For more information, see [Azure: Create and deploy OpenAI](https://learn.microsoft.com/en-us/azure/ai-services/openai/how-to/create-resource?pivots=web-portal)
 
@@ -55,31 +74,32 @@ For more information, see [Azure: Create and deploy OpenAI](https://learn.micros
    ![Creating an OpenAI service](pixels/config-azure-openai-create.png)
     - Select the subscription
     - Select a resource group or create a new one
-    - Select the region. Note that the region determines the available models.
-   > For instance, **Canada East** offers GPT-4-32k models, For the full list, see [GPT-4 models](https://learn.microsoft.com/en-us/azure/ai-services/openai/concepts/models)
+    - Select the region. **Important**: The region determines which models are available.
+   > Popular regions like **East US**, **West Europe**, and **Australia East** typically have the best model availability. For the latest model availability by region, see [Azure OpenAI Model Availability](https://learn.microsoft.com/en-us/azure/ai-services/openai/concepts/models)
     - Name the service (e.g., `your-openai-api-1234`)
     - Select a pricing tier (e.g., `S0` for standard)
     - Select: "All networks, including the internet, can access this resource."
     - Click on **Review + create** and then **Create**
 
-After creating the resource, you can access the API Keys and Endpoints. At any point, you can go to
-the OpenAI Service instance page to get this information.
+After creating the resource, you can access the API Keys and Endpoints:
 
-- Click on **Go to resource**
-- Click on **Develop**
-    - Copy the `Endpoint`, called "Language API", e.g. 'https://your-openai-api-1234.openai.azure.com/'
-    - Copy `KEY 1`
+1. Click on **Go to resource** (or navigate to your Azure OpenAI resource)
+2. In the left sidebar, under **Resource Management**, click on **Keys and Endpoint** 
+3. Copy the required information:
+   - **Endpoint**: e.g., 'https://your-resource-name.openai.azure.com/'
+   - **Key**: Copy either KEY 1 or KEY 2 (both work identically)
 
-### Step 4: Deploy Models
+### Step 3: Deploy Models
 
 By default, Azure OpenAI resource instances don't have models available. You need to deploy the models you want to use.
 
-1. Click on **Model Deployments > Manage Deployments**
-2. Click on **+Create New Deployment**
-   ![Deploying a model](pixels/config-azure-openai-deploy.png)
-    - Select the model you want to deploy
-    - Optionally select a version
-    - name the model, e.g., `gpt4-32k-0613`
+1. In your Azure OpenAI resource, click on **Model deployments** in the left sidebar
+2. Click on **Create new deployment** 
+3. Fill in the deployment details:
+   - **Select a model**: Choose from available models
+   - **Model version**: Select the latest version or a specific one
+   - **Deployment name**: Give it a meaningful name
+4. Click **Deploy**
 
 Repeat as necessary for each model you want to deploy.
 

docs/config-feature-browse.md

@@ -68,7 +68,7 @@ The chat agent won't be able to access the web sites if the browserless containe
       - MAX_CONCURRENT_SESSIONS=10
 ```
 
-You can then add the proyy lines to your `.env` file.
+You can then add the proxy lines to your `.env` file.
 
 ```
 https_proxy=http://PROXY-IP:PROXY-PORT
@@ -115,4 +115,4 @@ If you encounter any issues or have questions about configuring the browse funct
 
 Enjoy the enhanced browsing experience within `big-AGI` and explore the web without ever leaving your chat!
 
-Last updated on Feb 27, 2024 ([edit on GitHub](https://github.com/enricoros/big-AGI/edit/main/docs/config-feature-browse.md))
+Last updated on Feb 27, 2024 ([edit on GitHub](https://github.com/enricoros/big-AGI/edit/main/docs/config-feature-browse.md))

docs/config-local-localai.md

@@ -54,7 +54,7 @@ If the running LocalAI instance is configured with a [Model Gallery](https://loc
 
 At the time of writing, LocalAI does not publish the model `context window size`.
 Every model is assumed to be capable of chatting, and with a context window of 4096 tokens.
-Please update the [src/modules/llms/transports/server/openai/models.data.ts](../src/modules/llms/server/openai/models.data.ts)
+Please update the [src/modules/llms/transports/server/openai/models/models.data.ts](../src/modules/llms/server/openai/models/models.data.ts)
 file with the mapping information between LocalAI model IDs and names/descriptions/tokens, etc.
 
 # 🤝 Support

docs/config-local-ollama.md

@@ -72,15 +72,20 @@ Then, edit the nginx configuration file `/etc/nginx/sites-enabled/default` and a
 
 ```nginx
     location /ollama/ {
-        proxy_pass http://localhost:11434;
-        proxy_http_version 1.1;
-        proxy_set_header Upgrade $http_upgrade;
-        proxy_set_header Connection 'upgrade';
-        proxy_set_header Host $host;
-        proxy_cache_bypass $http_upgrade;
+        proxy_pass http://127.0.0.1:11434/;
 
-        # Disable buffering for the streaming responses
+        # Disable buffering for the streaming responses (SSE)
+        proxy_set_header Connection '';
+        proxy_http_version 1.1;
+        chunked_transfer_encoding off;
         proxy_buffering off;
+        proxy_cache off;
+        
+        # Longer timeouts (1hr)
+        keepalive_timeout 3600;
+        proxy_read_timeout 3600;
+        proxy_connect_timeout 3600;
+        proxy_send_timeout 3600;
     }
 ```
 

docs/config-local-oobabooga.md

@@ -1,61 +0,0 @@
-# Local LLM Integration with `text-web-ui` :llama:
-
-Integrate local Large Language Models (LLMs) with
-[oobabooga/text-generation-webui](https://github.com/oobabooga/text-generation-webui),
-a specialized interface that includes a custom variant of the OpenAI API for a smooth integration process.
-
-_Last updated on Dec 7, 2023_
-
-### Components
-
-The implementation of local LLMs involves the following components:
-
-* **text-generation-webui**: A Python application with a Gradio web UI for operating Large Language Models.
-    * **Local Large Language Models "LLMs"**: Use large language models on your personal computer with consumer-grade GPUs or CPUs.
-* **big-AGI**: An LLM UI that offers features such as Personas, OCR, Voice Support, Code Execution, AGI functions, and more.
-
-## Instructions
-
-This guide assumes that **big-AGI** is already installed on your system. Note that the text-generation-webui IP address must be accessible from the server running **big-AGI**.
-
-### Text-web-ui Installation & Configuration:
-
-1. Install [text-generation-webui](https://github.com/oobabooga/text-generation-webui#Installation):
-    - Follow the instructions in the official page (basicall clone the repo and run a script) [~10 minutes]
-    - Stop the Web UI as we need to modify the startup flags to enable the OpenAI API
-2. Enable the **openai extension**
-    - Edit `CMD_FLAGS.txt`
-    - Make sure that `--listen --api` is present and uncommented
-3. Restart text-generation-webui
-    - Double-click on "start"
-    - You should see something like:
-      ```
-      2023-12-07 21:51:21 INFO:Loading the extension "openai"...
-      2023-12-07 21:51:21 INFO:OpenAI-compatible API URL:
-
-      http://0.0.0.0:5000
-      ...
-      INFO:     Uvicorn running on http://0.0.0.0:5000 (Press CTRL+C to quit)
-      Running on local URL:  http://0.0.0.0:7860
-      ```
-    - This shows that:
-      - The Web UI is running on port 7860: http://127.0.0.1:7860
-      - **The OpenAI API is running on port 5000: http://127.0.0.1:5000**
-4. Load your first model
-    - Open the text-generation-webui at [127.0.0.1:7860](http://127.0.0.1:7860/)
-    - Switch to the **Model** tab
-    - Download, for instance, `TheBloke/Llama-2-7B-Chat-GPTQ`
-    - Select the model once it's loaded
-
-### Integrating text-web-ui with big-AGI:
-1. Integrating Text-Generation-WebUI with big-AGI:
-    - Go to Models > Add a model source of type: **Oobabooga**
-    - Enter the address: `http://127.0.0.1:5000`
-        - If running remotely, replace 127.0.0.1 with the IP of the machine. Make sure to use the **IP:Port** format
-    - Load the models
-        - The active model must be selected and LOADED on the text-generation-webui as it doesn't support model switching or parallel requests.
-    - Select model & Chat
-
-![config-oobabooga-0.png](pixels/config-oobabooga-0.png)
-
-Enjoy the privacy and flexibility of local LLMs with `big-AGI` and `text-generation-webui`!

docs/customizations.md

@@ -31,17 +31,14 @@ At time of writing, big-AGI has only 2 operations that run on Node.js Functions:
 browsing (fetching web pages) and sharing. They both can exceed 10 seconds, especially
 when fetching large pages or waiting for websites to be completed.
 
-We provide `vercel_PRODUCTION.json` to raise the duration to 25 seconds (from a default of 10), to use it,
-make sure to rename it to `vercel.json` before build.
-
 From the Vercel Project > Settings > General > Build & Development Settings,
 you can for instance set the build command to:
 
 ```bash
-mv vercel_PRODUCTION.json vercel.json; next build
+next build
 ```
 
-### Change the Personas
+### Change the Personas (v1.x only)
 
 Edit the `src/data.ts` file to customize personas. This file houses the default personas. You can add, remove, or modify these to meet your project's needs.
 
@@ -55,16 +52,41 @@ Adapt the UI to match your project's aesthetic, incorporate new features, or exc
 - [ ] Modify `src/common/app.config.tsx` to alter the application's name
 - [ ] Update `src/common/app.nav.tsx` to revise the navigation bar
 
+### Add a Message of the Day
+
+You can display a temporary announcement banner at the top of the app using the `NEXT_PUBLIC_MOTD` environment variable.
+
+- Set this variable in your deployment environment
+- The message supports template variables:
+  - `{{app_build_hash}}`: Current git commit hash
+  - `{{app_build_pkgver}}`: Package version
+  - `{{app_build_time}}`: Build timestamp as date
+  - `{{app_deployment_type}}`: Deployment type (local, docker, vercel, etc.)
+- Users can dismiss the message (until next page refresh)
+- Use it for version announcements, maintenance notices, or feature highlights
+
+Example: `NEXT_PUBLIC_MOTD=🚀 New features available in {{app_build_pkgver}}! Try the improved Beam.`
+
 ## Testing & Deployment
 
 Test your application thoroughly using local development (refer to README.md for local build instructions). Deploy using your preferred hosting service. big-AGI supports deployment on platforms like Vercel, Docker, or any Node.js-compatible service, especially those supporting NextJS's "Edge Runtime."
 
 - [deploy-cloudflare.md](deploy-cloudflare.md): for Cloudflare Workers deployment
 - [deploy-docker.md](deploy-docker.md): for Docker deployment instructions and examples
+- [deploy-k8s.md](deploy-k8s.md): for Kubernetes deployment instructions and examples
 
 ## Debugging
 
-We introduced the `/info/debug` page that provides a detailed overview of the application's environment, including the API keys, environment variables, and other configuration settings.
+The application includes a client-side logging system. You can view recent logs via the UI (Settings > Tools > Logs).
+
+For deeper debugging during development:
+
+1. **Debug Page**: Access the `/info/debug` page for an overview of the application's environment, configuration, API status, and environment variables available to the client.
+2. **Conditional Breakpoints**: To automatically pause execution in your browser's developer tools when critical errors (`error`, `critical`, `DEV` levels) are logged to the console, set the following environment variable in your local `.env.local` file and restart your development server:
+   ```bash
+   NEXT_PUBLIC_DEBUG_BREAKS=true
+   ```
+   This allows you to inspect the application state at the exact moment an important error occurs. This feature only works in development mode (`npm run dev`) and requires the environment variable to be explicitly set to `true`.
 
 <br/>
 

docs/deploy-analytics.md

@@ -2,8 +2,9 @@
 
 The open-source big-AGI project provides support for the following analytics services:
 
-- **Vercel Analytics**: automatic when deployed to Vercel
 - **Google Analytics 4**: manual setup required
+- **PostHog Analytics**: manual setup required
+- **Vercel Analytics**: automatic when deployed to Vercel
 
 The following is a quick overview of the Analytics options for the deployers of this open-source project.
 big-AGI is deployed to many large-scale and enterprise though various ways (custom builds, Docker, Vercel, Cloudflare, etc.),
@@ -11,6 +12,36 @@ and this guide is for its customization.
 
 ## Service Configuration
 
+### Google Analytics 4
+
+- Why: user engagement and retention, performance insights, personalization, content optimization
+- What: https://support.google.com/analytics/answer/11593727
+
+Google Analytics 4 (GA4) is a powerful tool for understanding user behavior and engagement.
+This can help optimize big-AGI, understanding which features are needed/users and which aren't.
+
+To enable Google Analytics 4, you need to set the `NEXT_PUBLIC_GA4_MEASUREMENT_ID` environment variable
+before starting the local build or the docker build (i.e. at build time), at which point the
+server/container will be able to report analytics to your Google Analytics 4 property.
+
+As of Feb 27, 2024, this feature is in development.
+
+### PostHog Analytics
+
+- Why: feature usage tracking, user journeys, conversion optimization, product analytics
+- What: page views, page leave events, user interactions, and deployment context
+
+PostHog provides comprehensive product analytics with privacy controls. It helps understand how users interact with big-AGI's features, identify opportunities for improvement, and optimize the user experience.
+
+To enable PostHog, set the `NEXT_PUBLIC_POSTHOG_KEY` environment variable at build time. PostHog is configured with tracking optimization and privacy in mind:
+
+- Uses a proxy endpoint (`/a/ph`) to avoid ad blockers
+- Respects user opt-out preferences via local storage
+- Tracks only essential information without PII
+- Adds deployment context for better segmentation
+
+The implementation follows PostHog's best practices for Next.js applications and includes manual page view tracking for proper single-page application support.
+
 ### Vercel Analytics
 
 - Why: understand coarse traction, and identify deployment issues - all without tracking individual users
@@ -31,33 +62,19 @@ const MyApp = ({ Component, emotionCache, pageProps }: MyAppProps) => <>
 </>;
 ```
 
-When big-AGI is served on Vercel hosts, the ```process.env.NEXT_PUBLIC_VERCEL_URL``` environment variable is trueish, and
+When big-AGI is served on Vercel hosts, the `process.env.NEXT_PUBLIC_VERCEL_URL` environment variable is trueish, and
 analytics will be sent by default to the Vercel Analytics service which is deployed by Vercel IF configured from the
 Vercel project dashboard.
 
 In summary: to turn it on: activate the `Analytics` service in the Vercel project dashboard.
 
-### Google Analytics 4
-
-- Why: user engagement and retention, performance insights, personalization, content optimization
-- What: https://support.google.com/analytics/answer/11593727
-
-Google Analytics 4 (GA4) is a powerful tool for understanding user behavior and engagement.
-This can help optimize big-AGI, understanding which features are needed/users and which aren't.
-
-To enable Google Analytics 4, you need to set the `NEXT_PUBLIC_GA4_MEASUREMENT_ID` environment variable
-before starting the local build or the docker build (i.e. at build time), at which point the
-server/container will be able to report analytics to your Google Analytics 4 property.
-
-As of Feb 27, 2024, this feature is in development.
-
 ## Configurations
 
-| Scope                                                                                   | Default          | Description / Instructions                                                                                              |
-|-----------------------------------------------------------------------------------------|------------------|-------------------------------------------------------------------------------------------------------------------------|
-| Your source builds of big-AGI                                                           | None             | **Vercel**: enable Vercel Analytics from the dashboard. · **Google Analytics**: set environment variable at build time. |
-| Your docker builds of big-AGI                                                           | None             | **Vercel**: n/a. · **Google Analytics**: set environment variable at `docker build` time.                               |
-| [big-agi.com](https://big-agi.com)                                                      | Vercel + Google  | The main website ([privacy policy](https://big-agi.com/privacy)) hosted for free for anyone.                            |
-| [official Docker packages](https://github.com/enricoros/big-AGI/pkgs/container/big-agi) | Google Analytics | **Vercel**: n/a · **Google Analytics**: set to the big-agi.com Google Analytics for analytics and improvements.         |
+| Scope                                                                                                                   | Default                   | Description / Instructions                                                                                                                                                  |
+|-------------------------------------------------------------------------------------------------------------------------|---------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| Your **Source** builds of big-AGI                                                                                       | None                      | **Google Analytics**: set environment variable at build time · **PostHog**: set environment variable at build time · **Vercel**: enable Vercel Analytics from the dashboard | 
+| Your **Docker** builds of big-AGI                                                                                       | None                      | (**Vercel**: n/a) · **Google Analytics**: set environment variable at `docker build` time · **PostHog**: set environment variable at `docker build` time.                   |
+| [get.big-agi.com](https://get.big-agi.com) (**Big-AGI 1.x Legacy**)                                                     | Vercel + Google + PostHog | The main website ([privacy policy](https://big-agi.com/privacy)) hosted for free for anyone.                                                                                |
+| [prebuilt Docker packages](https://github.com/enricoros/big-AGI/pkgs/container/big-agi) (**Big-AGI 1.x**, 'latest' tag) | Google Analytics          | **Vercel**: n/a · **Google Analytics**: set to the big-agi.com Google Analytics for analytics and improvements · **PostHog**: n/a                                           |
 
-Note: this information is updated as of Feb 27, 2024 and can change at any time.
+Note: this information is updated as of March 3, 2025 and can change at any time.

docs/deploy-authentication.md

@@ -19,7 +19,7 @@ To enable it in `big-AGI`, you **must manually build the application**:
 - Build `big-AGI` with HTTP authentication enabled:
   - Clone the repository
   - Rename `middleware_BASIC_AUTH.ts` to `middleware.ts`
-  - Build: usual simple build procedure (e.g. [Deploy manually](../README.md#-deploy-manually) or [Deploying with Docker](deploy-docker.md))
+  - Build: usual simple build procedure (e.g. [Deploy manually](installation.md#Local-Production-build) or [Deploying with Docker](deploy-docker.md))
 
 - Configure the following [environment variables](environment-variables.md) before launching `big-AGI`:
 ```dotenv

docs/deploy-cloudflare.md

@@ -34,7 +34,7 @@ Fork the repository to your personal GitHub account.
 2. On this page, set your **Project name**, **Production branch** (e.g., main), and your Build settings
 3. Choose `Next.js` from the **Framework preset** dropdown menu
 4. Set a custom **Build Command**:
-    - `rm app/api/trpc-node/[trpc]/route.ts && npx @cloudflare/next-on-pages@1`
+    - `rm app/api/cloud/[trpc]/route.ts && npx @cloudflare/next-on-pages@1`
     - see the tradeoffs for this deletion on the notice at the top
 5. Keep the **Build output directory** as default
 6. Click the **Save and Deploy** button

docs/deploy-docker.md

@@ -31,6 +31,12 @@ file.
 
 ### Official Images: [ghcr.io/enricoros/big-agi](https://github.com/enricoros/big-agi/pkgs/container/big-agi)
 
+#### Available Tags
+
+- **`:latest`** / **`:stable`** - Latest stable release (recommended)
+- **`:development`** - Main branch (bleeding edge)
+- **`:v2.0.0`** - Specific versions
+
 #### Run using *docker* 🚀
 
 ```bash
@@ -59,6 +65,17 @@ To make local services running on your host machine accessible to a Docker conta
 
 <br/>
 
+### Reverse Proxy Configuration
+
+A reverse proxy is a server that sits in front of big-AGI's container and can forwards web
+requests to it. Often used to run multiple web applications, expose them to the internet,
+increase security.
+
+If you're deploying big-AGI behind a reverse proxy, you may want to see
+our [Reverse Proxy Deployment Guide](deploy-reverse-proxy.md) for more information.
+
+<br/>
+
 ### More Information
 
 The [`Dockerfile`](../Dockerfile) describes how to create a Docker image. It establishes a Node.js environment,

docs/deploy-k8s.md

@@ -0,0 +1,85 @@
+# Deploy `big-AGI` with Kubernetes ☸️
+
+In this tutorial, we will guide you through the process of deploying big-AGI
+in a Kubernetes environment using the kubectl command-line tool.
+
+## First Deployment
+
+### Step 1: Clone the big-AGI repository
+
+```bash
+$ git clone https://github.com/enricoros/big-agi
+$ cd ./big-agi/docs/k8s
+```
+
+### Step 2: Create the namespace
+
+```bash
+$ kubectl create namespace ns-big-agi
+```
+
+### Step 3: Fill in the key information into env-secret.yaml
+
+All variables are optional. By default, Kubernetes Secret uses Base64 for
+encode/decode, so please don't do a git commit after filling in the keys
+to avoid leaking sensitive information.
+
+We provide an empty `env-secret.yaml` file as a template.
+You can fill in the necessary information using a text editor.
+
+```bash
+$ nano env-secret.yaml
+```
+
+### Step 4: Deploying Kubernetes Resources
+
+```bash
+$ kubectl apply -f big-agi-deployment.yaml -f env-secret.yaml
+```
+
+### Step 5: Verifying the Resource Statuses
+
+```bash
+$ kubectl -n ns-big-agi get svc,pod,deployment
+NAME                  TYPE        CLUSTER-IP     EXTERNAL-IP   PORT(S)    AGE
+service/svc-big-agi   ClusterIP   10.0.198.118   <none>        3000/TCP   63m
+
+NAME                                     READY   STATUS    RESTARTS   AGE
+pod/deployment-big-agi-xxxxxxxx-yyyyy    1/1     Running   0          39m
+
+NAME                              READY   UP-TO-DATE   AVAILABLE   AGE
+deployment.apps/deployment-big-agi   1/1     1            1           63m
+```
+
+### Step 6: Testing the Service
+
+You can test the service by port-forwarding the service to your local machine:
+
+```bash
+$ kubectl -n ns-big-agi port-forward service/svc-big-agi 3000
+Forwarding from 127.0.0.1:3000 -> 3000
+Forwarding from [::1]:3000 -> 3000
+```
+
+Now you can access the service at `http://localhost:3000`, and you should see the big-AGI homepage.
+
+## Updating big-AGI
+
+To update big-AGI to the latest version:
+
+1. Pull the latest changes from the repository:
+   ```bash
+   $ git pull origin main
+   ```
+
+2. Apply the updated deployment:
+   ```bash
+   $ kubectl apply -f big-agi-deployment.yaml
+   ```
+
+This will trigger a rolling update of the deployment with the latest image.
+
+**Note**: If you're deploying big-AGI behind a reverse proxy, you may need to configure
+your proxy to support streaming. See our [Reverse Proxy Deployment Guide](deploy-reverse-proxy.md) for more information.
+
+Note: For production use, consider setting up an Ingress Controller or Load Balancer instead of using port-forward.

docs/deploy-reverse-proxy.md

@@ -0,0 +1,58 @@
+# Advanced: Deploying big-AGI behind a Reverse Proxy
+
+Note: if you don't have a reverse proxy set up, you can skip this guide.
+
+If you're deploying big-AGI behind a reverse proxy, you may want to configure your proxy to support streaming output.
+This guide provides instructions on how to configure your reverse proxy to support streaming output from big-AGI.
+
+This is for advanced deployments, and you should have a basic understanding of how reverse proxies work.
+
+## Nginx Configuration
+
+If you're using Nginx as your reverse proxy, add the following configuration to your server block:
+
+```nginx
+server {
+    listen 80;
+    server_name your-domain.com;
+
+    location / {
+        # ...your specific proxy_pass configuration, example below...
+        proxy_pass http://localhost:3000;  # Assuming big-AGI is running on port 3000
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection 'upgrade';
+        proxy_set_header Host $host;
+        proxy_cache_bypass $http_upgrade;
+        # ...
+
+        # Important: Disable buffering for the streaming responses (SSE)
+        chunked_transfer_encoding on;   # Turn on chunked transfer encoding
+        proxy_buffering off;            # Turn off proxy buffering
+        proxy_cache off;                # Turn off caching
+        tcp_nodelay on;                 # Turn on TCP NODELAY option, disable delay ACK algorithm
+        tcp_nopush on;                  # Turn on TCP NOPUSH option, disable Nagle algorithm
+
+        # Important: Longer timeouts (5 min)
+        keepalive_timeout 300;
+        proxy_connect_timeout 300;
+        proxy_read_timeout 300;
+        proxy_send_timeout 300;
+    }
+}
+```
+
+This configuration disables caching and buffering, enables chunked transfer encoding, and adjusts TCP settings to optimize for streaming content.
+
+## Troubleshooting
+
+If you're experiencing issues with streaming not working, especially when deploying behind a reverse proxy,
+ensure that your proxy is configured to support streaming output as described above.
+
+## Additional Resources
+
+- For Docker deployments, see our [Docker Deployment Guide](deploy-docker.md)
+- For Kubernetes deployments, see our [Kubernetes Deployment Guide](deploy-k8s.md)
+- For general installation instructions, see our [Installation Guide](installation.md)
+
+If you continue to experience issues, please reach out to our [community support channels](../README.md#-get-involved).

docs/environment-variables.md

@@ -3,7 +3,7 @@
 This document provides an explanation of the environment variables used in the big-AGI application.
 
 **All variables are optional**; and _UI options_ take precedence over _backend environment variables_,
-which take place over _defaults_. This file is kept in sync with [`../src/server/env.mjs`](../src/server/env.mjs).
+which take place over _defaults_. This file is kept in sync with [`../src/server/env.ts`](../src/server/env.ts).
 
 ### Setting Environment Variables
 
@@ -23,44 +23,49 @@ MDB_URI=
 OPENAI_API_KEY=
 OPENAI_API_HOST=
 OPENAI_API_ORG_ID=
+ALIBABA_API_HOST=
+ALIBABA_API_KEY=
 AZURE_OPENAI_API_ENDPOINT=
 AZURE_OPENAI_API_KEY=
 ANTHROPIC_API_KEY=
 ANTHROPIC_API_HOST=
+DEEPSEEK_API_KEY=
 GEMINI_API_KEY=
 GROQ_API_KEY=
 LOCALAI_API_HOST=
 LOCALAI_API_KEY=
 MISTRAL_API_KEY=
 OLLAMA_API_HOST=
+OPENPIPE_API_KEY=
 OPENROUTER_API_KEY=
 PERPLEXITY_API_KEY=
 TOGETHERAI_API_KEY=
+XAI_API_KEY=
 
 # Model Observability: Helicone
 HELICONE_API_KEY=
 
-# Text-To-Speech
-ELEVENLABS_API_KEY=
-ELEVENLABS_API_HOST=
-ELEVENLABS_VOICE_ID=
-# Text-To-Image
-PRODIA_API_KEY=
-# Google Custom Search
-GOOGLE_CLOUD_API_KEY=
-GOOGLE_CSE_ID=
 # Browse
 PUPPETEER_WSS_ENDPOINT=
 
-# Backend Analytics
-BACKEND_ANALYTICS=
+# Search
+GOOGLE_CLOUD_API_KEY=
+GOOGLE_CSE_ID=
+
+# Text-To-Speech: ElevenLabs
+ELEVENLABS_API_KEY=
+ELEVENLABS_API_HOST=
+ELEVENLABS_VOICE_ID=
 
 # Backend HTTP Basic Authentication (see `deploy-authentication.md` for turning on authentication)
 HTTP_BASIC_AUTH_USERNAME=
 HTTP_BASIC_AUTH_PASSWORD=
 
-# Frontend variables
+
+# Frontend variables 
+NEXT_PUBLIC_MOTD=
 NEXT_PUBLIC_GA4_MEASUREMENT_ID=
+NEXT_PUBLIC_POSTHOG_KEY=
 NEXT_PUBLIC_PLANTUML_SERVER_URL=
 ```
 
@@ -80,24 +85,32 @@ For Database configuration see [deploy-database.md](deploy-database.md).
 The following variables when set will enable the corresponding LLMs on the server-side, without
 requiring the user to enter an API key
 
-| Variable                    | Description                                                                                                                   | Required                                                          |
-|-----------------------------|-------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------|
-| `OPENAI_API_KEY`            | API key for OpenAI                                                                                                            | Recommended                                                       |
-| `OPENAI_API_HOST`           | Changes the backend host for the OpenAI vendor, to enable platforms such as Helicone and CloudFlare AI Gateway                | Optional                                                          |
-| `OPENAI_API_ORG_ID`         | Sets the "OpenAI-Organization" header field to support organization users                                                     | Optional                                                          |
-| `AZURE_OPENAI_API_ENDPOINT` | Azure OpenAI endpoint - host only, without the path                                                                           | Optional, but if set `AZURE_OPENAI_API_KEY` must also be set      |
-| `AZURE_OPENAI_API_KEY`      | Azure OpenAI API key, see [config-azure-openai.md](config-azure-openai.md)                                                    | Optional, but if set `AZURE_OPENAI_API_ENDPOINT` must also be set |
-| `ANTHROPIC_API_KEY`         | The API key for Anthropic                                                                                                     | Optional                                                          |
-| `ANTHROPIC_API_HOST`        | Changes the backend host for the Anthropic vendor, to enable platforms such as [config-aws-bedrock.md](config-aws-bedrock.md) | Optional                                                          |
-| `GEMINI_API_KEY`            | The API key for Google AI's Gemini                                                                                            | Optional                                                          |
-| `GROQ_API_KEY`              | The API key for Groq Cloud                                                                                                    | Optional                                                          |
-| `LOCALAI_API_HOST`          | Sets the URL of the LocalAI server, or defaults to http://127.0.0.1:8080                                                      | Optional                                                          |
-| `LOCALAI_API_KEY`           | The (Optional) API key for LocalAI                                                                                            | Optional                                                          |
-| `MISTRAL_API_KEY`           | The API key for Mistral                                                                                                       | Optional                                                          |
-| `OLLAMA_API_HOST`           | Changes the backend host for the Ollama vendor. See [config-local-ollama.md](config-local-ollama)                             |                                                                   |
-| `OPENROUTER_API_KEY`        | The API key for OpenRouter                                                                                                    | Optional                                                          |
-| `PERPLEXITY_API_KEY`        | The API key for Perplexity                                                                                                    | Optional                                                          |
-| `TOGETHERAI_API_KEY`        | The API key for Together AI                                                                                                   | Optional                                                          |
+| Variable                    | Description                                                                                                    | Required                                                          |
+|-----------------------------|----------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------|
+| `OPENAI_API_KEY`            | API key for OpenAI                                                                                             | Recommended                                                       |
+| `OPENAI_API_HOST`           | Changes the backend host for the OpenAI vendor, to enable platforms such as Helicone and CloudFlare AI Gateway | Optional                                                          |
+| `OPENAI_API_ORG_ID`         | Sets the "OpenAI-Organization" header field to support organization users                                      | Optional                                                          |
+| `ALIBABA_API_HOST`          | The Alibaba AI OpenAI-compatible endpoint                                                                      | Optional                                                          |
+| `ALIBABA_API_KEY`           | The API key for Alibaba AI                                                                                     | Optional                                                          |
+| `AZURE_OPENAI_API_ENDPOINT` | Azure OpenAI endpoint - host only, without the path                                                            | Optional, but if set `AZURE_OPENAI_API_KEY` must also be set      |
+| `AZURE_OPENAI_API_KEY`      | Azure OpenAI API key, see [config-azure-openai.md](config-azure-openai.md)                                     | Optional, but if set `AZURE_OPENAI_API_ENDPOINT` must also be set |
+| `AZURE_OPENAI_DISABLE_V1`   | Disables the next-generation v1 API for GPT-5-like models (set to 'true' to disable)                          | Optional, defaults to enabled                                     |
+| `AZURE_OPENAI_API_VERSION`  | API version for traditional deployment-based endpoints                                                          | Optional, defaults to '2025-04-01-preview'                       |
+| `AZURE_DEPLOYMENTS_API_VERSION` | API version for the deployments listing endpoint                                                            | Optional, defaults to '2023-03-15-preview'                       |
+| `ANTHROPIC_API_KEY`         | The API key for Anthropic                                                                                      | Optional                                                          |
+| `ANTHROPIC_API_HOST`        | Changes the backend host for the Anthropic vendor, to enable platforms such as AWS Bedrock                     | Optional                                                          |
+| `DEEPSEEK_API_KEY`          | The API key for Deepseek AI                                                                                    | Optional                                                          |
+| `GEMINI_API_KEY`            | The API key for Google AI's Gemini                                                                             | Optional                                                          |
+| `GROQ_API_KEY`              | The API key for Groq Cloud                                                                                     | Optional                                                          |
+| `LOCALAI_API_HOST`          | Sets the URL of the LocalAI server, or defaults to http://127.0.0.1:8080                                       | Optional                                                          |
+| `LOCALAI_API_KEY`           | The (Optional) API key for LocalAI                                                                             | Optional                                                          |
+| `MISTRAL_API_KEY`           | The API key for Mistral                                                                                        | Optional                                                          |
+| `OLLAMA_API_HOST`           | Changes the backend host for the Ollama vendor. See [config-local-ollama.md](config-local-ollama.md)           |                                                                   |
+| `OPENPIPE_API_KEY`          | The API key for OpenPipe                                                                                       | Optional                                                          |
+| `OPENROUTER_API_KEY`        | The API key for OpenRouter                                                                                     | Optional                                                          |
+| `PERPLEXITY_API_KEY`        | The API key for Perplexity                                                                                     | Optional                                                          |
+| `TOGETHERAI_API_KEY`        | The API key for Together AI                                                                                    | Optional                                                          |
+| `XAI_API_KEY`               | The API key for xAI                                                                                            | Optional                                                          |
 
 ### LLM Observability: Helicone
 
@@ -121,15 +134,12 @@ Enable the app to Talk, Draw, and Google things up.
 | `ELEVENLABS_API_KEY`       | ElevenLabs API Key - used for calls, etc.                                                                               |
 | `ELEVENLABS_API_HOST`      | Custom host for ElevenLabs                                                                                              |
 | `ELEVENLABS_VOICE_ID`      | Default voice ID for ElevenLabs                                                                                         |
-| **Text-To-Image**          | [Prodia](https://prodia.com/) is a reliable image generation service                                                    |
-| `PRODIA_API_KEY`           | Prodia API Key - used with '/imagine ...'                                                                               |
 | **Google Custom Search**   | [Google Programmable Search Engine](https://programmablesearchengine.google.com/about/)  produces links to pages        |
 | `GOOGLE_CLOUD_API_KEY`     | Google Cloud API Key, used with the '/react' command - [Link to GCP](https://console.cloud.google.com/apis/credentials) |
 | `GOOGLE_CSE_ID`            | Google Custom/Programmable Search Engine ID - [Link to PSE](https://programmablesearchengine.google.com/)               |
 | **Browse**                 |                                                                                                                         |
 | `PUPPETEER_WSS_ENDPOINT`   | Puppeteer WebSocket endpoint - used for browsing (pade downloadeing), etc.                                              |
 | **Backend**                |                                                                                                                         |
-| `BACKEND_ANALYTICS`        | Semicolon-separated list of analytics flags (see backend.analytics.ts). Flags: `domain` logs the responding domain.     |
 | `HTTP_BASIC_AUTH_USERNAME` | See the [Authentication](deploy-authentication.md) guide. Username for HTTP Basic Authentication.                       |
 | `HTTP_BASIC_AUTH_PASSWORD` | Password for HTTP Basic Authentication.                                                                                 |
 
@@ -137,10 +147,13 @@ Enable the app to Talk, Draw, and Google things up.
 
 The value of these variables are passed to the frontend (Web UI) - make sure they do not contain secrets.
 
-| Variable                          | Description                                                                              |
-|:----------------------------------|:-----------------------------------------------------------------------------------------|
-| `NEXT_PUBLIC_GA4_MEASUREMENT_ID`  | The measurement ID for Google Analytics 4. (see [deploy-analytics](deploy-analytics.md)) |
-| `NEXT_PUBLIC_PLANTUML_SERVER_URL` | The URL of the PlantUML server, used for rendering UML diagrams. (code in RederCode.tsx) |
+| Variable                          | Description                                                                                                                                                                                                                                     |
+|:----------------------------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `NEXT_PUBLIC_DEBUG_BREAKS`        | (optional, development) When set to 'true', enables automatic debugger breaks on DEV/error/critical logs in development builds                                                                                                                  |
+| `NEXT_PUBLIC_MOTD`                | Message of the Day - displays a dismissible banner at the top of the app (see [customizations](customizations.md) for the template variables). Example: 🔔 Welcome to our deployment! Version {{app_build_pkgver}} built on {{app_build_time}}. |
+| `NEXT_PUBLIC_GA4_MEASUREMENT_ID`  | (optional) The measurement ID for Google Analytics 4. (see [deploy-analytics](deploy-analytics.md))                                                                                                                                             |
+| `NEXT_PUBLIC_POSTHOG_KEY`         | (optional) Key for PostHog analytics. (see [deploy-analytics](deploy-analytics.md))                                                                                                                                                             |
+| `NEXT_PUBLIC_PLANTUML_SERVER_URL` | The URL of the PlantUML server, used for rendering UML diagrams. Allows using custom local servers.                                                                                                                                             |
 
 > Important: these variables must be set at build time, which is required by Next.js to pass them to the frontend.
 > This is in contrast to the backend variables, which can be set when starting the local server/container.

docs/help-advanced-tricks.md

@@ -0,0 +1,42 @@
+# Big-AGI Advanced Tips & Tricks
+
+> 🚨 This file is not meant for publication, and it's just been created as a handbook with tips
+> and tricks to make Big-AGI more efficient and productive. 🚨
+
+Welcome to the advanced tips and tricks guide for Big-AGI. This document will help you make the most of the platform's existing features.
+
+---
+
+## Hidden Gems
+
+- **Shift + Double-Click** on a chat message to **edit** it.
+- **Shift + Trash Icon** to **delete** a chats and messages without confirmation.
+  - also applies elsewhere: delete Attachments, etc.
+- **Shift + Click** on **New Chat** to create an incognito chat.
+- Drag a big-AGI saved chat into Big-AGI to load (or attach) it.
+
+## Not-so-obvious Shortcuts
+
+- When sending a message:
+  - Enter is for newlines
+  - **Shift + Enter** to send the message.
+  - **Ctrl + Enter** to **Beam** the message.
+  - **Alt/Option + Enter** to send the message without an answer.
+- When editing a message:
+  - **Ctrl + Enter** to **Save** the changes.
+  - **Shift + Ctrl + Enter** to **Save & Regenerate**.
+- Scroll between messages:
+  - **Ctrl + Up/Down** to scroll between **messages** and/or **Beams**.
+  
+## Worth the Effort:
+
+- [LiveFile](help-feature-livefile.md) works on **Chrome**: Pair and synchronize your documents and code blocks with files on your local system: refresh, save, update them.
+
+## Best User Hacks:
+
+- 
+
+---
+
+Note: this document is just at the beginning. It's here so we can capture
+the best tips over time.

docs/help-data-ownership.md

@@ -0,0 +1,99 @@
+# Big-AGI Data Ownership Guide
+
+Big-AGI is a **client-first** web application, which means it prioritizes speed and data ownership compared to cloud apps.
+Your *API keys*, *chat history*, and *settings* live in your
+browser's [local storage](https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage), not
+on cloud servers.
+
+You can use Big-AGI in two ways:
+
+1. Run it yourself (open-source)
+2. Use big-agi.com (hosted service)
+
+This guide explains how the open-source version handles your data. You can verify everything in [the source code](https://github.com/enricoros/big-agi).
+
+## Client-Side Storage
+
+Within Big-AGI almost all chat/keys data is handled client-side in your browser using two
+standard browser storage mechanisms:
+
+- **Local Storage**: API keys, settings, and configurations ([learn more](https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage))
+- **IndexedDB**: Chat history and larger files ([learn more](https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API))
+
+The Big-AGI backend mainly passes requests to AI services (OpenAI, Anthropic, etc.). It doesn't store your data, except for the chat-sharing function if used.
+
+You can see your data in your browser's local storage and IndexedDB - try it yourself:
+
+1. In Chrome: Open DevTools (press F12 on Windows, ⌘ + ⌥ + I on Mac)
+2. Click 'Application' > 'Local Storage'
+3. See your settings and API keys
+
+![Browser local storage showing API keys and chat data](pixels/data_ownership_local_storage.png)
+
+### What This Means For You
+
+Storing data in your browser means:
+
+- Your data stays on **one device/browser only**
+- Clearing browser data **erases your chats** - make backups
+- Anyone using your browser can see your chats and keys
+- Running your own server needs technical skills
+
+### Local Device Identifier
+
+Big-AGI generates a _device identifier_ that combines timestamp and random components, stored only on your device. This identifier:
+
+- Is used only for the **optional sync functionality** between your devices (not yet ready)
+- Helps maintain data consistency when using Big-AGI across multiple devices
+- Remains completely local unless you explicitly enable sync
+- Is not used for tracking, analytics, or telemetry
+- Can be deleted anytime by clearing local storage
+- Is fully transparent - see the implementation in `src/common/stores/store-client.ts`
+
+## How Data Flows
+
+AI interactions in Big-AGI, such as chats, AI titles, text to speech, browsing, flow through three components:
+
+1. **Browser** (client/installed App) - Stores your keys & data locally
+2. **Backend** (routing server) - Passes requests to AI services
+3. **AI Services** - Where the actual AI processing happens
+
+### Self-Deployed Version: Your Infrastructure
+
+You run the server. Your data only leaves when making AI requests.
+The keys and chats are under your control and pass through your code, and are sent to
+the upstream AI services on a per-request basis.
+
+![data_ownership_local.png](pixels/data_ownership_deployed.png)
+
+### Web Version: Using big-agi.com
+
+Your data passes through the hosted Big-AGI edge network to reach AI services. The keys
+and chats pass through Big-AGI's edge network to reach the AI services on a per-request basis,
+and then are send to the upstream AI services.
+
+![data_ownership_hosted.png](pixels/data_ownership_hosted.png)
+
+## Security Best Practices
+
+**Basic Security**:
+
+- **Never share API keys**
+- **Don't use shared computers**
+- Use private browsing for one-off sessions
+- Use trusted networks
+- Back up your data
+
+**When Running Your Own Server**:
+
+- Use [environment variables](environment-variables.md) for API keys
+- Run on trusted infrastructure
+- Keep your installation updated
+
+## TL;DR
+
+Your API keys and chats stay in your browser. The server only passes requests to AI services.
+
+Use big-agi.com for convenience, or [run it yourself](installation.md) for full control.
+
+Need help? Join our [Discord](https://discord.gg/MkH4qj2Jp9) or open a [GitHub issue](https://github.com/enricoros/big-agi/issues).

docs/help-faq.md

@@ -0,0 +1,28 @@
+# Frequently Asked Questions
+
+Quick answers to common questions about Big-AGI. For detailed documentation, see our [Website Docs](https://big-agi.com/docs).
+
+### Versions
+
+<details open>
+<summary><b>How do I check my Big-AGI version?</b></summary>
+
+You can see the version in the _News_ section of the app, as per the image below.
+
+![Version location in Big-AGI](https://github.com/user-attachments/assets/cd295094-0114-420f-a5b9-0d762e59b506)
+</details>
+
+<details open>
+<summary><b>How do I verify my Vercel deployment version?</b></summary>
+
+You can go in the **deployments** section of your Vercel project, and at a quick glance see
+what is the latest deployment status, time, and link to the source code.
+
+![Vercel deployments view](https://github.com/user-attachments/assets/664b8c3d-496e-4595-ad5e-898bdb82507c)
+
+Each deployment links directly to its source code commit.
+</details>
+
+---
+
+Missing something? [Open an issue](https://github.com/enricoros/big-agi/issues/new) or [join our Discord](https://discord.gg/MkH4qj2Jp9).

docs/help-feature-livefile.md

@@ -0,0 +1,167 @@
+# LiveFile: Synchronize Your Documents with Local Files
+
+## Introduction
+
+**LiveFile** is a powerful feature in big-AGI that allows you to **pair and synchronize
+your documents and code blocks** with files on your local system.
+
+This feature enables a **two-way connection between big-AGI and your local files on disk**,
+saving you time and effort.
+
+With LiveFile, you can:
+
+- **Pair** documents and code blocks with local files.
+- **Monitor** changes in local files and update content in big-AGI.
+- **Refresh** chat attachments with the latest content.
+- **Save** edits made in big-AGI back to your local files.
+- **Store** AI-generated code and content.
+
+---
+
+## Requirements
+
+- **Supported Browsers:**
+  - **Google Chrome** (desktop)
+  - **Microsoft Edge** (desktop)
+- **Operating Systems:**
+  - **Desktop platforms only**
+  - **Note:** Mobile devices (iOS and Android) are **not supported** due to browser limitations.
+- **File Types:**
+  - Designed for **text-based files** (e.g., `.txt`, `.md`, `.js`, `.py`).
+- **Performance:**
+  - Can handle **dozens of files efficiently**.
+- **Limitations:**
+  - **File Size Limit**: 
+    - Supports text files up to **10 MB**.
+  - **Pairing Persistence:**
+    - LiveFile connections **do not persist across sessions**.
+    - After reloading the page, you will need to re-pair your files.
+  - **Saving Overwrites:**
+    - Saving changes in big-AGI will **overwrite the entire file**.
+    - Use external tools for version control or incremental backups.
+
+---
+
+## Enabling LiveFile
+
+LiveFile can be enabled automatically or manually in your Big-AGI workflow.
+
+### Automatic Pairing
+
+When you:
+
+- **Attach**, **drop**, or **paste** a file into a chat message,
+
+LiveFile is **automatically enabled** for that attachment. This means you can start
+monitoring and reloading changes without any additional setup.
+
+### Manual Pairing
+
+For existing attachments or code blocks that:
+
+- **Do not have LiveFile enabled** (e.g., created on other devices),
+- **Are AI-generated code snippets without an associated file**,
+
+You can manually pair them with a local file.
+
+#### Pairing Attachments
+
+1. **Select the Attachment:**
+  - Click on the attachment in the chat to view it in the previewer.
+
+2. **Initiate Pairing:**
+  - Click on **"Pair File"** (🔗).
+  - If you have open LiveFiles, they will be listed for easy selection.
+  - Alternatively, you can select a new file from your local system.
+
+3. **Grant Permissions**
+  - When prompted, allow big-AGI to access the file.
+
+#### Pairing Code Blocks
+
+1. **Access Code Block Options:**
+  - Click on the code block to reveal the header with options.
+
+2. **Initiate Pairing:**
+  - Click the **"Pair File"** button (🔗).
+  - Select from your open LiveFiles or choose a new file.
+
+3. **Confirm Pairing:**
+  - Grant permission when prompted.
+
+---
+
+## Using LiveFile
+
+### Monitoring Changes
+
+- **Automatic Monitoring:**
+  - LiveFile watches for changes in your paired local files.
+  - If the file is modified outside of big-AGI, you'll be shown the changes in the LiveFile bar.
+  - There is also a **"Replace with File"** option to manually load the latest content and see the changes.
+
+- **Refreshing Content:**
+  - Click **"Replace with File"** (🔄) to load the latest content from the paired file into big-AGI.
+
+### Saving Edits Back to Paired Files
+
+- **Editing Attachments or Code Blocks:**
+  - Modify the content directly within big-AGI.
+  - Attachments: Click on the attachment to open the previewer and click on "Edit" to make changes.
+  - Code Blocks: Select "Edit" on the chat message to update code blocks.
+
+- **Saving Changes:**
+  - Click **"Save to File"** (💾) to overwrite the local file with your changes.
+  - **Note:** This action overwrites the entire file. Ensure this is what you want before proceeding.
+
+---
+
+## Best Practices
+
+- **Monitor External Changes:**
+  - Refresh content in big-AGI if the local file has been modified outside the application.
+
+- **Use a Version Control System:**
+  - For critical files, consider using Git or other version control systems to track and monitor changes, authorship, and history.
+
+---
+
+## Troubleshooting
+
+- **LiveFile Options Not Visible:**
+  - Ensure you are using a **supported desktop browser**.
+  - Check that you have the latest version of big-AGI.
+
+- **Permission Issues:**
+  - Confirm that you granted big-AGI permission to access your files.
+  - Check your browser's settings to ensure file access is allowed.
+
+---
+
+## Technical Details
+
+LiveFile uses the [File System Access API](https://developer.mozilla.org/en-US/docs/Web/API/File_System_Access_API) to 
+interact with your local files securely. It leverages the [browser-fs-access](https://github.com/GoogleChromeLabs/browser-fs-access) library, 
+an open-source project by Google Chrome Labs, which provides an easy interface to the File System Access API with fallbacks for broader browser support.
+
+- **Security:**
+  - Access to files requires explicit user permission.
+
+- **Performance:** 
+  - Designed to handle dozens of files efficiently (tested on hundreds).
+  - Works with the Big-AGI attachment system to recursively add directories.
+
+- **Browser Support:**
+  - Fully supported on **Google Chrome** and **Microsoft Edge** desktop versions.
+
+---
+
+## Another Big-AGI First!
+
+You can significantly boost your productivity and streamline your workflow within big-AGI
+by understanding how to utilize LiveFile's features fully.
+
+This Feature is in Beta as there are a few limitations and improvements to be made. 
+Join us in enjoying and enhancing this feature on [big-AGI.com](https://big-agi.com), or
+[GitHub](https://github.com/enricoros/big-AGI) for support and [Discord](https://discord.gg/MkH4qj2Jp9)
+to share the love.

docs/help-feature-microphone.md

@@ -0,0 +1,141 @@
+# Enabling Microphone Access for Speech Recognition
+
+This guide explains how to enable microphone access for speech recognition in various browsers and mobile devices.
+Ensuring microphone access is essential for using voice features in applications like big-AGI.
+
+## Desktop Browsers
+
+### Google Chrome (All Platforms, recommended)
+
+1. Open the website (e.g., big-AGI) in Chrome.
+2. Click the **lock icon** in the address bar.
+3. In the dropdown, find **"Microphone"**.
+   - Set it to **"Allow"**.
+4. If "Microphone" isn't listed:
+   - Click on **"Site settings"**.
+   - Find **"Microphone"** in the permissions list.
+   - Change the setting to **"Allow"**.
+5. **Refresh** the page.
+
+### Safari (macOS)
+
+**[Watch the video tutorial: How to enable Speech Recognition in Safari](https://vimeo.com/1010342201)**
+
+If you're seeing a "Speech Recognition permission denied" error, follow these steps:
+
+1. Open **System Settings**.
+   - Go to **Privacy & Security** > **Speech Recognition**.
+   - Enable Safari in the list of allowed applications.
+   - Quit & Open Safari.
+2. Click **Safari** in the top menu bar.
+   - Select **Settings**.
+   - Go to the **Websites** tab.
+   - Select **Microphone** from the sidebar.
+   - Find big-AGI (or localhost for developers) in the list and set it to **Allow**.
+   - Close the Settings window.
+3. **Refresh** the page.
+
+This quick and simple fix should get essential voice input working in big-AGI on your Mac.
+
+### Microsoft Edge (Windows)
+
+1. Open the website in Edge.
+2. Click the **lock icon** in the address bar.
+3. Click **"Permissions for this site"**.
+4. Find **"Microphone"**.
+   - Set it to **"Allow"**.
+5. **Refresh** the page.
+
+### Firefox (All Platforms)
+
+> **Note:** The Speech Recognition API is **not supported** in Firefox. If you're using Firefox, please switch to a supported browser to use speech recognition
+> features.
+
+## Mobile Devices
+
+### Android (Chrome)
+
+1. Open the website in Chrome.
+2. Tap the **lock icon** in the address bar.
+3. Tap **"Permissions"**.
+4. Find **"Microphone"**.
+   - Set it to **"Allow"**.
+5. **Refresh** the page.
+
+### iOS (Safari)
+
+1. Open the **Settings** app on your device.
+2. Scroll down and tap **"Safari"**.
+3. Tap **"Microphone"**.
+4. Ensure **"Ask"** or **"Allow"** is selected.
+5. Return to Safari and open the website.
+6. If prompted, allow microphone access.
+7. **Refresh** the page.
+
+### iOS (Chrome)
+
+> **Note:** Chrome on iOS uses Safari's engine due to system limitations. Microphone permissions are managed through iOS settings.
+
+1. Open the **Settings** app.
+2. Scroll down and tap **"Chrome"**.
+3. Ensure **"Microphone"** is toggled **on**.
+4. Open Chrome and navigate to the website.
+5. If prompted, allow microphone access.
+6. **Refresh** the page.
+
+## Troubleshooting
+
+If you're still experiencing issues after enabling microphone access:
+
+**Check System Permissions (macOS):**
+
+- Open **System Settings**.
+- Go to **"Privacy & Security"**.
+- Select the **"Privacy"** tab.
+- Click **"Microphone"** in the sidebar.
+- Ensure your browser (e.g., Chrome, Safari) is checked.
+- You may need to unlock the settings by clicking the lock icon at the bottom.
+
+**Check Microphone Access (Windows):**
+
+- Open **Settings**.
+- Go to **"Privacy"** > **"Microphone"**.
+- Ensure **"Allow apps to access your microphone"** is **on**.
+- Scroll down and make sure your browser is allowed.
+
+**Close Other Applications:**
+
+- Close any applications that might be using the microphone.
+
+**Restart the Browser:**
+
+- Close all browser windows and reopen.
+
+**Update Your Browser:**
+
+- Ensure you're using the latest version.
+
+**Check for Browser Extensions:**
+
+- Disable extensions that might block access to the microphone.
+
+For persistent issues, consult your browser's official support resources or contact big-AGI support.
+
+## Technical Details
+
+Big-AGI uses the [Web Speech API (SpeechRecognition)](https://developer.mozilla.org/en-US/docs/Web/API/SpeechRecognition)
+to transcribe spoken words into text. This API provides real-time transcription with live previews and works on most
+modern mobile and desktop browsers.
+
+**Note on Browser Support:**
+
+| Browser        | Support Level   | Notes                                                                  |
+|----------------|-----------------|------------------------------------------------------------------------|
+| Google Chrome  | ✅ Recommended   | Fully supported on desktop and Android. Preferred for best experience. |
+| Safari         | ✅ Supported     | Requires macOS/iOS 14 or later.                                        |
+| Microsoft Edge | ✅ Supported     | Fully supported on desktop.                                            |
+| Firefox        | ❌ Not Supported | SpeechRecognition API not available.                                   |
+
+**Recommendation:**
+For the best experience with speech recognition features, we strongly recommend using Google Chrome. 
+Ensure your browser is up to date to benefit from the latest features and security updates.

docs/installation.md

@@ -47,10 +47,10 @@ the same steps 1 and 2 as for [local development](#local-development).
    # .. repeat the steps above up to `npm install`, then:
    npm run build
    ```
-4. Start the production server:
+4. Start the production server (`npx` may be optional):
    ```bash
-    next start --port 3000
-    ```
+   npx next start --port 3000
+   ```
    Your big-AGI production instance is on `http://localhost:3000`.
 
 ### Advanced Customization
@@ -99,6 +99,43 @@ or follow the steps below for a quick start.
    ```
    Access your big-AGI instance at `http://localhost:3000`.
 
+If you deploy big-AGI behind a reverse proxy, you may want to check out the [Reverse Proxy Configuration Guide](deploy-reverse-proxy.md).
+
+### Kubernetes Deployment
+
+Deploy big-AGI on a Kubernetes cluster for enhanced scalability and management. Follow these steps for a Kubernetes deployment:
+
+1. Clone the big-AGI repository:
+   ```bash
+   git clone https://github.com/enricoros/big-AGI.git
+   cd big-AGI
+   ```
+
+2. Configure the environment variables:
+   ```bash
+   cp docs/k8s/env-secret.yaml env-secret.yaml
+   vim env-secret.yaml  # Edit the file to set your environment variables
+   ```
+
+3. Apply the Kubernetes configurations:
+   ```bash
+   kubectl create namespace ns-big-agi
+   kubectl apply -f docs/k8s/big-agi-deployment.yaml -f env-secret.yaml
+   ```
+
+4. Verify the deployment:
+   ```bash
+   kubectl -n ns-big-agi get svc,pod,deployment
+   ```
+
+5. Access the big-AGI application:
+   ```bash
+   kubectl -n ns-big-agi port-forward service/svc-big-agi 3000:3000
+   ```
+   Your big-AGI instance is now accessible at `http://localhost:3000`.
+
+For more detailed instructions on Kubernetes deployment, including updating and troubleshooting, refer to our [Kubernetes Deployment Guide](deploy-k8s.md).
+
 ### Midori AI Subsystem for Docker Deployment
 
 Follow the instructions found on [Midori AI Subsystem Site](https://io.midori-ai.xyz/subsystem/manager/)
@@ -114,6 +151,6 @@ Enjoy all the features of big-AGI without the hassle of infrastructure managemen
 Join our vibrant community of developers, researchers, and AI enthusiasts. Share your projects, get help, and collaborate with others.
 
 - [Discord Community](https://discord.gg/MkH4qj2Jp9)
-- [Twitter](https://twitter.com/yourusername)
+- [Twitter](https://twitter.com/enricoros)
 
-For any questions or inquiries, please don't hesitate to [reach out to our team](mailto:hello@big-agi.com).
+For any questions or inquiries, please don't hesitate to [reach out to our team](mailto:hello@big-agi.com).

docs/k8s/big-agi-deployment.yaml

@@ -0,0 +1,52 @@
+---
+apiVersion: v1
+kind: Namespace
+metadata:
+  name: ns-big-agi
+---
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  labels:
+    app: big-agi
+  name: deployment-big-agi
+  namespace: ns-big-agi
+spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      app: big-agi
+  strategy: {}
+  template:
+    metadata:
+      labels:
+        app: big-agi
+    spec:
+      containers:
+        - image: ghcr.io/enricoros/big-agi:latest
+          name: big-agi
+          ports:
+            - containerPort: 3000
+          args:
+            - next
+            - start
+            - -p
+            - "3000"
+          envFrom:
+            - secretRef:
+                name: env
+---
+apiVersion: v1
+kind: Service
+metadata:
+  labels:
+    app: big-agi
+  name: svc-big-agi
+  namespace: ns-big-agi
+spec:
+  ports:
+    - name: "http"
+      port: 3000
+      targetPort: 3000
+  selector:
+    app: big-agi

docs/k8s/env-secret.yaml

@@ -0,0 +1,48 @@
+---
+apiVersion: v1
+kind: Secret
+metadata:
+  name: env
+  namespace: ns-big-agi
+type: Opaque
+stringData:
+  # IMPORTANT: This file contains sensitive information. Do not commit changes to version control.
+  # All variables are optional. Fill in only the ones you need.
+  #
+  # For the latest information on all the environment variables, see /docs/environment-variables.md
+  #
+
+  # LLMs
+  OPENAI_API_KEY: ""
+  OPENAI_API_HOST: ""
+  OPENAI_API_ORG_ID: ""
+  ALIBABA_API_HOST: ""
+  ALIBABA_API_KEY: ""
+  AZURE_OPENAI_API_ENDPOINT: ""
+  AZURE_OPENAI_API_KEY: ""
+  ANTHROPIC_API_KEY: ""
+  ANTHROPIC_API_HOST: ""
+  DEEPSEEK_API_KEY: ""
+  GEMINI_API_KEY: ""
+  GROQ_API_KEY: ""
+  LOCALAI_API_HOST: ""
+  LOCALAI_API_KEY: ""
+  MISTRAL_API_KEY: ""
+  OLLAMA_API_HOST: ""
+  OPENPIPE_API_KEY: ""
+  OPENROUTER_API_KEY: ""
+  PERPLEXITY_API_KEY: ""
+  TOGETHERAI_API_KEY: ""
+  XAI_API_KEY: ""
+
+  # Browse
+  PUPPETEER_WSS_ENDPOINT: ""
+
+  # Search
+  GOOGLE_CLOUD_API_KEY: ""
+  GOOGLE_CSE_ID: ""
+
+  # Text-To-Speech: Eleven Labs
+  ELEVENLABS_API_KEY: ""
+  ELEVENLABS_API_HOST: ""
+  ELEVENLABS_VOICE_ID: ""

docs/use-chat-react.md

@@ -0,0 +1,43 @@
+# ReAct: question answering with Reasoning and Actions
+
+## What is ReAct?
+
+[ReAct](https://arxiv.org/abs/2210.03629) (Reason+Act) is a classis AI question-answering feature,
+that combines reasoning with actions to provide informed answers.
+
+Within Big-AGI, users can invoke ReAct to ask complex questions that require multiple steps to answer.
+
+| Mode  | Activation                        | Information Sources                                  | Reasoning Visibility               | When to Use                                      |
+|-------|-----------------------------------|------------------------------------------------------|------------------------------------|--------------------------------------------------|
+| Chat  | Just type and send                | **Pre-trained knowledge only**                       | Only shows final response          | Quick answers, general knowledge queries         |
+| ReAct | Type "/react" before the question | **Web loads, Web searches, Wikipedia, calculations** | Shows step-by-step thought process | Complex, multi-step, or research-based questions |
+
+Example of ReAct in action, taking a question about current events, googling results, opening a page, and summarizing the information:
+
+https://github.com/user-attachments/assets/c3480428-9ab8-4257-a869-2541bf44a062
+
+The following tools are implemented in Big-AGI:
+
+- **browse**: loads web pages (URLs) and extracts information, using a correctly configured `Tools > Browsing` API
+- **search**: searches the web to produce page URLs, using a correctly configured `Tools > Google Search` ([Google Programmable Search Engine](https://programmablesearchengine.google.com/about/)) API
+- **wikipedia**: looks up information on Wikipedia pages
+- **calculate**: performs mathematical calculations by executing typescript code
+  - warning: (!) unsafe and dangerous, do not use for untrusted code/LLMs
+
+## How to Use ReAct in Big-AGI
+
+1. **Invoking ReAct**: Type "/react" followed by your question in the chat.
+2. **What to Expect**:
+
+- An ephemeral space will show the AI's thought process and actions, showing all the steps taken.
+- The final answer will appear in the main chat.
+
+3. **Available Actions**: Web searches, Wikipedia lookups, calculations, and optionally web browsing.
+
+## Good to know:
+
+- **ReAct operates in isolation** from the main chat history.
+- It **will take longer than standard responses** due to multiple steps.
+- Web searches and browsing may have privacy implications, and require **tool configuration** in the UI.
+- Errors or limitations in accessing external resources may affect results.
+- ReAct does not use the [Tool or Function Calling](https://platform.openai.com/docs/guides/function-calling) feature of AI models, rather uses the old school approach of parsing and executing actions.

kb/KB.md

@@ -0,0 +1,35 @@
+# Knowledge Base
+
+Internal documentation for Big-AGI architecture and systems, for use by AI agents and developers.
+
+**Structure:**
+- `/kb/modules/` - Core business logic (e.g. AIX)
+- `/kb/systems/` - Infrastructure (routing, startup)
+
+## Index
+
+### Modules Documentation
+
+#### AIX - AI Communication Framework
+- **[AIX.md](modules/AIX.md)** - AIX streaming architecture documentation
+- **[AIX-callers-analysis.md](modules/AIX-callers-analysis.md)** - Analysis of AIX entry points, call chains, common and different rendering, error handling, etc.
+
+### Systems Documentation
+
+#### Core Platform Systems
+- **[app-routing.md](systems/app-routing.md)** - Next.js routing, provider stack, and display state hierarchy
+- **[LLM-parameters-system.md](systems/LLM-parameters-system.md)** - Language model parameter flow across the system
+
+## Guidelines
+
+### Writing Style
+
+- **Direct and factual** - No marketing language
+- **Present tense** - "AIX handles streaming" not "AIX will handle"
+- **Active voice** - "The system processes" not "Processing is done by"
+- **Concrete examples** - Show actual code/config when helpful, briefly
+
+### Maintenance
+
+- Remove outdated information when detected!
+- Keep cross-references current when files move

kb/modules/AIX-callers-analysis.md

@@ -0,0 +1,144 @@
+# AIX Chat Generation Calls Analysis
+
+This document analyzes all AIX function callers and their patterns for message removal, placeholder handling, and error management.
+
+## AIX Function Architecture
+
+### Three-Tier Call Hierarchy
+
+**Core AIX Functions** (Direct tRPC API callers):
+- `aixChatGenerateContent_DMessage_FromConversation` - 8 callers (conversation streaming)
+- `aixChatGenerateContent_DMessage` - 6 callers (direct request/response)
+- `aixChatGenerateText_Simple` - 12 callers (text-only utilities)
+
+**Utility Layer** (Hooks & Functions):
+- Conversation management, persona processing, content generation utilities
+
+**UI Layer** (React Components):
+- User-facing interfaces with rich error states and fallback mechanisms
+
+## Core Function Callers Analysis
+
+### Conversation-Based Callers (`_FromConversation`)
+
+| **Caller** | **Context** | **Message Removal** | **Placeholder** | **Error Handling** |
+|------------|-------------|-------------------|----------------|-------------------|
+| **Chat Persona** | `'conversation'` | `messageWasInterruptedAtStart()` → `removeMessage()` | None | Error fragments |
+| **Beam Scatter** | `'beam-scatter'` | `messageWasInterruptedAtStart()` → empty message | `SCATTER_PLACEHOLDER` | Ray status update |
+| **Beam Gather** | `'beam-gather'` | `messageWasInterruptedAtStart()` → clear fragments | `GATHER_PLACEHOLDER` | Re-throw errors |
+| **Beam Follow-up** | `'beam-followup'` | `messageWasInterruptedAtStart()` → remove message | `FOLLOWUP_PLACEHOLDER` | Status updates |
+| **ScratchChat** | `'scratch-chat'` | `aborted && !fragments` → array removal | `SCRATCH_CHAT_PLACEHOLDER` | Error fragments |
+| **Telephone** | `'call'` | None | None | Basic handling |
+| **ReAct Agent** | `'chat-react-turn'` | None | None | Append errors |
+| **Variform** | `'_DEV_'` | None | None | Throw errors |
+
+### Direct Request Callers (`aixChatGenerateContent_DMessage`)
+
+| **Caller** | **Context** | **Message Removal** | **Error Handling** |
+|------------|-------------|-------------------|-------------------|
+| **Auto Follow-ups** | `'chat-followup-*'` | `fragmentDelete()` on failure | `fragmentReplace()` with error |
+| **Gen CR Diffs** | `'aifn-gen-cr-diffs'` | None | State-based handling |
+| **Code Fixup** | `'fixup-code'` | None | Throw errors |
+| **Attachment Prompts** | `'chat-attachment-prompts'` | None | Throw errors |
+
+### Text-Only Utilities (`aixChatGenerateText_Simple`)
+
+| **Utility** | **Purpose** | **Error Strategy** | **Called By** |
+|-------------|-------------|-------------------|---------------|
+| **conversationTitle** | Auto-generate chat titles | Try/catch with fallback | UI components |
+| **conversationSummary** | Generate summaries | Try/catch with fallback | Chat drawer |
+| **useStreamChatText** | Generic text streaming | Error state management | FlattenerModal |
+| **useLLMChain** | Multi-step processing | Step-by-step handling | Persona creation |
+| **imaginePromptFromText** | Text → image prompts | Simple propagation | Image generation |
+| **aifnBeamGenerateBriefing** | Beam summaries | Null return on error | Beam completion |
+| **useAifnPersonaGenIdentity** | Extract persona identity | Query error handling | Persona flows |
+| **DiagramsModal** | Generate diagrams | Component error state | Manual generation |
+
+## Message Removal Patterns
+
+### 1. Complete Message Removal
+- **Chat Persona**: `messageWasInterruptedAtStart()` → `messageEditor.removeMessage()`
+- **ScratchChat**: `outcome === 'aborted' && !fragments?.length` → array removal
+- **Trigger**: Message aborted before any content generated
+
+### 2. Fragment-Level Management
+- **Beam Gather**: Clear fragments array but keep message structure
+- **Auto Follow-ups**: Delete specific placeholder fragments on failure
+- **Purpose**: Maintain message structure while removing failed content
+
+### 3. Empty Message Replacement
+- **Beam Scatter**: Replace with `createDMessageEmpty()` but preserve ray structure
+- **Purpose**: Keep UI structure intact while indicating failure
+
+### 4. No Removal Strategy
+- **Text-only functions**: Use fallback values, error states, or null returns
+- **Simple callers**: Propagate errors upstream for handling
+
+## Error Handling by Layer
+
+### UI Layer (Components)
+- **Pattern**: Rich error states with user-facing messages
+- **Examples**: DiagramsModal, FlattenerModal
+- **Features**: Retry mechanisms, fallback UI, loading states
+
+### Utility Layer (Hooks/Functions)
+- **Pattern**: Graceful degradation with fallbacks
+- **Examples**: conversationTitle, conversationSummary
+- **Features**: Silent failures, default values, try/catch blocks
+
+### Core Layer (Direct API)
+- **Pattern**: Minimal handling, error propagation
+- **Examples**: Code Fixup, Attachment Prompts
+- **Features**: Assumes upstream error handling
+
+## Key Implementation Details
+
+### Message Removal Detection
+```typescript
+// Core detection logic
+function messageWasInterruptedAtStart(message: Pick<DMessage, 'generator' | 'fragments'>): boolean {
+  return message.generator?.tokenStopReason === 'client-abort' && message.fragments.length === 0;
+}
+```
+
+### Placeholder Management
+- **Initialization**: `createPlaceholderVoidFragment(placeholderText)`
+- **Replacement**: During streaming updates or on completion
+- **Cleanup**: Delete on error to avoid stale content
+
+### Context Patterns
+- **Production**: `'conversation'`, `'beam-scatter'`, `'scratch-chat'`
+- **Features**: `'chat-followup-*'`, `'fixup-code'`, `'ai-diagram'`
+- **Development**: `'_DEV_'`
+
+## Best Practices
+
+### Message Removal
+- Use `messageWasInterruptedAtStart()` for consistent detection
+- Only remove messages with no content that were client-aborted
+- Consider UI context when choosing removal vs. clearing strategy
+
+### Error Handling
+- **Fragment-level**: Use `messageEditor.fragmentReplace()` with error fragments
+- **Message-level**: Use `messageEditor.removeMessage()` or array removal
+- **Status-level**: Update component state for UI feedback
+
+### Placeholder Management
+- Initialize with descriptive placeholders using `createPlaceholderVoidFragment()`
+- Replace during streaming updates
+- Clean up on error to prevent stale content
+
+## Architectural Insights
+
+1. **Layered Error Handling**: Sophistication increases closer to UI
+2. **Context Specialization**: Different contexts for different use cases
+3. **Streaming vs Non-Streaming**: Conversation functions stream, utilities typically don't
+4. **Message vs Fragment Management**: Different strategies for different UI needs
+
+The most sophisticated handling is in **Beam modules** and **Chat Persona** with comprehensive removal logic, while simpler callers rely on upstream error handling.
+
+## Code References
+
+- **Core function**: `src/modules/aix/client/aix.client.ts:aixChatGenerateContent_DMessage_FromConversation`
+- **Removal check**: `src/common/stores/chat/chat.message.ts:388:messageWasInterruptedAtStart()`
+- **Placeholder creation**: `src/common/stores/chat/chat.fragments.ts:createPlaceholderVoidFragment()`

kb/modules/AIX.md

@@ -0,0 +1,189 @@
+# AIX
+
+AIX is a client/server library for integrating advanced AI capabilities into web applications.
+
+## Overview
+
+AIX provides real-time, type-safe communication between a Typescript application and AI providers.
+
+Built with tRPC, it manages the lifecycle of AI-generated content from request to rendering, supporting both streaming and non-streaming AI providers.
+
+## Features
+
+- Content Generation
+  - Multi-Modal streaming/non-streaming
+  - Throttled batching and error handling
+  - Server-side timeout/retry
+- Function Calling and Code Execution
+- Complex AI Workflows (future)
+- Embeddings / Information Retrieval / Image Manipulation (future)
+
+## AIX Providers support
+
+| Service    | Chat       | Function Calling | Multi-Modal Input | Cont. (1) | Streaming | Idiosyncratic | 
+|------------|------------|------------------|-------------------|-----------|-----------|---------------|
+| Alibaba    | ✅          | ✅                |                   | ✅         | Yes + 📦  |               |
+| Anthropic  | ✅          | ✅ + Parallel     | Img: ✅            | ✅         | Yes + 📦  |               |
+| Azure      | ✅          | ✅                |                   | ✅         | Yes + 📦  |               |
+| Deepseek   | ✅          | ❌ (rejected)     |                   | ✅         | Yes + 📦  |               |
+| Gemini     | ✅          | ✅ + Parallel     | Img: ✅            | ✅         | Yes + 📦  | Code ex.: ✅   |
+| Groq       | ✅          | ✅ + Parallel     |                   | ✅         | Yes + 📦  |               |
+| LM Studio  | ✅          | ❌ (not working)  |                   | ❌         | Yes  + 📦 |               |
+| Local AI   | ✅          | ✅                |                   | ❌         | Yes  + 📦 |               |
+| Mistral    | ✅          | ✅                |                   | ✅         | Yes  + 📦 |               |
+| OpenAI     | ✅          | ✅ + Parallel     | Img: ✅            | ✅         | Yes + 📦  |               |
+| OpenPipe   | ✅          | ✅                | Img: ✅            | ✅         | Yes + 📦  |               |
+| OpenRouter | ✅          | ❌ (inconsistent) |                   | ✅         | Yes + 📦  |               |
+| Perplexity | ✅          | ❌ (rejected)     |                   | ✅         | Yes + 📦  |               |
+| TogetherAI | ✅          | ✅                |                   | ✅         | Yes + 📦  |               |
+| xAI        |            |                  |                   |           |           |               |
+| Ollama (2) | ❌ (broken) | ?                |                   |           |           |               |
+
+Notes:
+
+- 1: Continuation marks: a. sends reason=max-tokens (streaming/non-streaming), b. TBA
+- 2: Ollama has not been ported to AIX yet due to the custom APIs.
+
+## 1. System Architecture
+
+The subsystem comprises three main components:
+
+1. **Client (e.g. Next.js Frontend)**
+
+- Initiates requests
+- Renders AI-generated content in real-time
+- Reconstructs streamed data
+
+2. **Server (e.g. Next.js Backend)**
+
+- Acts as an intermediary between client and AI providers
+- Handles request preparation, dispatching, and response processing
+- Streams responses back to the client
+
+3. **Upstream AI Providers**
+
+- Generate AI content based on requests
+
+### ChatGenerate workflow:
+
+1. Request Initialization: AIX Client prepares and sends request (systemInstruction, messages=AixWire_Parts[], etc.) to AIX Server
+2. Dispatch Preparation: AIX Server prepares for upstream communication
+3. AI Provider Interaction: AIX Server communicates with AI Provider (streaming or non-streaming)
+4. Data Decoding, Transformation and Transmission: AIX Server sends AixWire_Particles to AIX Client
+5. Client-side Processing: Client's ContentReassembler processes AixWire_Particles into a list (likely a single) of multi-fragment (DMessageContentFragment[]) messages
+6. Completion: AIX Server sends 'done' control message, AIX Client finalizes data update
+7. Error Handling: AIX Server sends specific error messages when necessary
+
+## 2. Files and Folders
+
+AIX is organized into the following files and folders:
+
+1. Client-Side (`/client/`):
+
+- `aix.client.ts`: Main client-side entry point for AIX operations.
+- `aix.client.chatGenerateRequest.ts`: Handles conversion of chat messages to AIX-compatible format (AixWire_Content, AixWire_Parts, etc.).
+
+2. Server-Side (`/server/`):
+
+- API (`/server/api/`) - Client to Server communication:
+  - `aix.router.ts`: Defines the tRPC router for AIX operations.
+  - `aix.wiretypes.ts`: Contains Zod schemas for types and calls incoming from the client (AixWire_Parts, AixWire_Content, AixWire_Tooling, AixWire_API, ...), and outgoing (AixWire_Particles)
+
+- Dispatch (`/server/dispatch/`) - Server to AI Provider communication:
+  - `/server/dispatch/chatGenerate/`: Content Generation with chat-style inputs:
+    - `./adapters/`: Adapters for creating API requests for different AI protocols (Anthropic, Gemini, OpenAI).
+    - `./parsers/`: Parsers for parsing streaming/non-streamin responses from different AI protocols (same 3).
+    - `chatGenerate.dispatch.ts`: Creates a pipeline to execute Chat Generation to a specific provider.
+    - `ChatGenerateTransmitter.ts`: Used to serialize and transmit AixWire_Particles to the client.
+  - `/server/dispatch/wiretypes/`: AI provider Wire Types:
+    - Type definitions for different AI providers/protocols (Anthropic, Gemini, OpenAI).
+  - `stream.demuxers.ts`: Handles demuxing of different stream formats.
+
+## 3. Architecture Diagram
+
+```mermaid
+sequenceDiagram
+    participant AIX Client
+    participant AIX Server
+    participant PartTransmitter
+    participant AI Provider
+    AIX Client ->> AIX Client: Initialize ContentReassembler
+    AIX Client ->> AIX Client: Convert DMessage*Part to AixWire_Parts
+    AIX Client ->> AIX Server: Send messages (arrays of AixWire_Parts)
+    AIX Server ->> AIX Server: Prepare Dispatch (Upstream request, demux, parsing)
+
+    alt Dispatch Preparation Error
+        AIX Server ->> AIX Client: Send `dispatch-prepare` error message
+    else Dispatch Fetch
+        AIX Server ->> AI Provider: Send AI-provider specific stream/non-stream request
+        AIX Server ->> AIX Client: Send 'start' control message
+        AIX Server ->> PartTransmitter: Initialize part particle serialization
+
+        alt Streaming AI Provider
+            loop Until stream end or error
+                AI Provider ->> AIX Server: Stream response chunk
+                AIX Server ->> AIX Server: Demux chunk into DispatchEvents
+                loop For each AI-provider specific DispatchEvent
+                    AIX Server ->> AIX Server: Parse DispatchEvent
+                    AIX Server ->> PartTransmitter: (Parser) Calls serialization functions
+                    PartTransmitter ->> PartTransmitter: Generate and throttle AixWire_PartParticles
+                    PartTransmitter -->> AIX Server: Yield AixWire_PartParticle
+                end
+                AIX Server ->> AIX Client: Send accumulated AixWire_PartParticles
+            end
+            AIX Server ->> PartTransmitter: Request any remaining particles
+            PartTransmitter -->> AIX Server: Yield any final AixWire_PartParticles
+            AIX Server ->> AIX Client: Send final AixWire_PartParticles (if any)
+        else Non-Streaming AI Provider
+            AI Provider ->> AIX Server: Send AI-provider specific complete response
+            alt AI-provider specific full-response parser
+                AIX Server ->> AIX Server: Parse full response
+                AIX Server ->> PartTransmitter: Call particle serialization functions
+                PartTransmitter ->> PartTransmitter: Generate AixWire_PartParticle
+                PartTransmitter -->> AIX Server: Yield ALL AixWire_PartParticle
+            end
+            AIX Server ->> AIX Client: Send all AixWire_PartParticles
+        end
+        AIX Server ->> AIX Client: Send 'done' control message
+        loop For each received batch of particles
+            AIX Client ->> AIX Client: ContentReassembler processes particles into DMessage*Part
+            alt DMessageTextPart
+                AIX Client ->> AIX Client: Update UI with text content
+            else DMessageImageRefPart
+                AIX Client ->> AIX Client: Load and display image
+            else DMessageToolInvocationPart
+                AIX Client ->> AIX Client: Process tool invocation (dev only)
+            else DMessageToolResponsePart
+                AIX Client ->> AIX Client: Process tool response (dev only)
+            else DMessageErrorPart
+                AIX Client ->> AIX Client: Display error message
+            else DMessageDocPart
+                AIX Client ->> AIX Client: Process and display document
+            else DMetaPlaceholderPart
+                AIX Client ->> AIX Client: Handle placeholder (non-submitted)
+            end
+        end
+        AIX Client ->> AIX Client: Finalize data update
+    end
+
+    alt Error Handling
+        AIX Server ->> AIX Client: Send 'error' specific control messages
+    end
+
+    note over AIX Server, AI Provider: Server-side Timeout/Retry mechanism
+    loop Retry on timeout (server-side)
+        AIX Server ->> AI Provider: Retry request
+    end
+
+    note over AIX Client: Client-side Timeout mechanism
+    AIX Client ->> AIX Client: Timeout if no response received within set time
+```
+
+---
+
+### 2025-03-14 Update
+AIX is used in production in Big-AGI and is stable and performant.
+The code is tightly coupled with the tRPC framework and the rest of our codebase,
+so it is not recommended to use it outside of our ecosystem.
+
+For a great Typescript alternative we recommend the Vercel AI SDK.

kb/systems/LLM-parameters-system.md

@@ -0,0 +1,131 @@
+# LLM Parameters System
+
+This document describes how parameters flow through Big-AGI's LLM parameters system, from definition to API invocation.
+
+## System Overview
+
+The LLM parameters system operates across five layers that transform parameters from global definitions to vendor-specific API calls. Each layer serves a specific purpose in the parameter resolution pipeline.
+
+## Parameter Flow Architecture
+
+### Layer 1: Parameter Registry
+**File**: `src/common/stores/llms/llms.parameters.ts`
+
+The `DModelParameterRegistry` defines all available parameters with their constraints and metadata. Each parameter includes type information, validation rules, and default behavior.
+
+**Example**: `llmVndOaiReasoningEffort4` defines a 4-value enum with 'medium' as the required fallback.
+
+**Default Value System**: The registry supports multiple default mechanisms:
+- `initialValue` - Parameter's base default (e.g., `llmVndOaiRestoreMarkdown: true`)
+- `requiredFallback` - Fallback for required parameters (e.g., `llmTemperature: 0.5`)
+- `nullable` - Parameters that can be explicitly null to skip API transmission
+
+### Layer 2: Model Specifications
+**File**: `src/modules/llms/server/llm.server.types.ts`
+
+Models declare which parameters they support through `parameterSpecs` arrays. Each spec can override registry defaults:
+
+```typescript
+parameterSpecs: [
+  { paramId: 'llmVndOaiReasoningEffort4' },
+  { paramId: 'llmVndAntThinkingBudget', initialValue: 1024 }, // Override default
+  { paramId: 'llmVndGeminiThinkingBudget', rangeOverride: [0, 8192] }, // Custom range
+]
+```
+
+**Parameter Visibility**: The `hidden` flag removes parameters from the UI while keeping them functional. Models can also mark parameters as `required`.
+
+### Layer 3: Client Configuration
+
+The system provides two UI configurators with different scopes:
+
+#### Full Model Configuration Dialog
+**File**: `src/modules/llms/models-modal/LLMParametersEditor.tsx`
+Shows all non-hidden parameters from model's `parameterSpecs`. Used in the models modal for complete configuration.
+
+#### ChatPanel Quick Controls
+**File**: `src/apps/chat/components/layout-panel/ChatPanelModelParameters.tsx`
+Shows only parameters that are:
+- In model's `parameterSpecs`
+- Listed in `_interestingParameters` array
+- Not marked as `hidden`
+
+**Value Resolution**: Both UIs use `getAllModelParameterValues()` to merge:
+1. **Fallback values** - Required parameters get their `requiredFallback` values
+2. **Initial values** - Model's `initialParameters` (populated during model creation)
+3. **User values** - User's `userParameters` (highest priority)
+
+### Layer 4: AIX Translation
+**File**: `src/modules/aix/client/aix.client.ts`
+
+The AIX client transforms DLLM parameters to wire protocol format. This layer handles parameter precedence rules and name transformations:
+
+```typescript
+// Parameter precedence: newer 4-value version takes priority over 3-value
+...((llmVndOaiReasoningEffort4 || llmVndOaiReasoningEffort) ?
+  { vndOaiReasoningEffort: llmVndOaiReasoningEffort4 || llmVndOaiReasoningEffort } : {})
+```
+
+**Client Options**: The system supports parameter overrides through `llmOptionsOverride` and complete replacement via `llmUserParametersReplacement`.
+
+### Layer 5: Vendor Adaptation
+**Files**: `src/modules/aix/server/dispatch/chatGenerate/adapters/*.ts`
+
+Server-side adapters translate AIX parameters to vendor APIs. Each vendor may interpret parameters differently:
+
+- **OpenAI**: `vndOaiReasoningEffort` → `reasoning_effort`
+- **Perplexity**: Reuses OpenAI parameter format
+- **OpenAI Responses API**: Maps to structured reasoning config with additional logic
+
+## Parameter Initialization Process
+
+When a model is loaded:
+
+1. **Model Creation**: `modelDescriptionToDLLM()` creates the DLLM with empty `initialParameters`
+2. **Initial Value Application**: `applyModelParameterInitialValues()` populates initial values from:
+   - Model spec `initialValue` (highest priority)
+   - Registry `initialValue` (fallback)
+3. **Runtime Resolution**: `getAllModelParameterValues()` creates final parameter set:
+   - Required fallbacks (for missing required parameters)
+   - Initial parameters (model defaults)
+   - User parameters (user overrides)
+
+## Special Parameter Behaviors
+
+**Hidden Parameters**: Parameters like `llmRef` are marked `hidden: true` in the registry and never appear in the UI, but remain functional for system use.
+
+**Nullable Parameters**: Parameters with `nullable` configuration can be explicitly set to `null` to prevent transmission to the API, distinct from being undefined.
+
+**Range Overrides**: Models can override parameter ranges (e.g., different Gemini models support different thinking budget ranges).
+
+**Parameter Interactions**: The UI implements business logic like disabling web search when reasoning effort is 'minimal'.
+
+## Type Safety Mechanisms
+
+The system maintains type safety through:
+- `DModelParameterId` union from registry keys
+- `DModelParameterValue<T>` conditional types for values
+- `DModelParameterSpec<T>` interfaces for specifications
+- Runtime validation via Zod schemas at API boundaries
+
+## Model Variant Pattern
+
+Some vendors use model variants to enable features, for instance:
+- **Anthropic**: Creates separate `idVariant: 'thinking'` entries forcing value of hidden parameters
+- **Google/OpenAI**: Parameters directly on base models
+
+## Migration and Compatibility
+
+The architecture supports parameter evolution:
+- **Version Coexistence**: Both `llmVndOaiReasoningEffort` and `llmVndOaiReasoningEffort4` exist simultaneously
+- **Precedence Rules**: Newer parameters take priority during AIX translation
+- **Graceful Degradation**: Unknown parameters log warnings but don't break functionality
+
+## Key Implementation Files
+
+- **Registry**: `src/common/stores/llms/llms.parameters.ts`
+- **Specifications**: `src/modules/llms/server/llm.server.types.ts`
+- **UI Controls**: `src/modules/llms/models-modal/LLMParametersEditor.tsx`
+- **AIX Translation**: `src/modules/aix/client/aix.client.ts`
+- **Wire Types**: `src/modules/aix/server/api/aix.wiretypes.ts`
+- **Vendor Adapters**: `src/modules/aix/server/dispatch/chatGenerate/adapters/*.ts`

kb/systems/app-routing.md

@@ -0,0 +1,151 @@
+# Big-AGI Routing & Display States
+
+This document describes the routing architecture and display state hierarchy in Big-AGI, from top-level providers down to component-level states.
+
+## Overview
+
+Big-AGI uses Next.js Pages Router with a provider stack that determines what users see based on application state and configuration.
+
+## Quick Reference: Route Configurations
+
+| Route | Purpose | Key Features |
+|-------|---------|--------------|
+| `/` | Main chat app | Default application |
+| `/call` | Voice interface | Voice-to-voice AI conversations |
+| `/personas` | Persona management | Create and manage AI personas |
+| ... |  |  |
+
+## Decision Flow Diagram
+
+The routing decisions follow a hierarchy from system-level provider configuration down to component-level states.
+
+```mermaid
+flowchart TD
+    Start([Navigate to Route]) --> Root[_app.tsx]
+
+    Root --> Theme[ProviderTheming]
+    Theme --> Error[ErrorBoundary]
+    Error --> Bootstrap[ProviderBootstrapLogic]
+
+    Bootstrap --> BootCheck{Bootstrap Checks}
+    BootCheck -->|News| News[↗️ /news]
+    BootCheck -->|Continue| Router{Router}
+
+    Router -->|/| Chat[Chat App]
+    Router -->|/personas,/call,/beam...| OtherApps[Other Apps]
+    Router -->|/news| NewsApp[News App]
+
+    Chat --> ChatStates{Chat States}
+
+    ChatStates -->|No Models| ZeroModels[🟡 Setup Models]
+    ChatStates -->|No Conv| ZeroConv[🟡 Select Chat]
+    ChatStates -->|No Msgs| PersonaGrid[Choose Persona]
+    ChatStates -->|Ready| Active[🟢 Active Chat]
+
+    Active --> Features[Features:<br/>• Chat Bar<br/>• Beam Mode<br/>• Attachments]
+
+    style ZeroModels fill:#fff4cc
+    style ZeroConv fill:#fff4cc
+    style Active fill:#ccffcc
+    style Chat fill:#f0f8ff
+    style OtherApps fill:#f0f8ff
+    style NewsApp fill:#f0f8ff
+```
+
+## Display State Hierarchy
+
+```
+_app.tsx (Root)
+├── ProviderTheming ← Always Applied
+├── ErrorBoundary ← Always Applied
+├── ProviderBootstrapLogic ← Always Applied
+│   ├── Tiktoken preload & Model auto-config
+│   ├── Storage maintenance & cleanup
+│   └── News Redirect (if conditions met)
+│
+└── Page Component
+    ├── AppChat (/) → Default app
+    │   ├── CMLZeroModels → If no models configured
+    │   ├── CMLZeroConversation → If no conversation selected
+    │   └── PersonaGrid → If conversation empty
+    │
+    └── Other Apps → Personas, Call, Draw, News, Beam
+```
+
+## Provider Stack
+
+| Provider | Purpose | Key Functions |
+|----------|---------|---------------|
+| **ProviderTheming** | UI theme management | Theme switching, CSS variables |
+| **ErrorBoundary** | Error handling | Catches and displays errors gracefully |
+| **ProviderBootstrapLogic** | App initialization | • Tiktoken preload<br>• Model auto-config<br>• Storage cleanup<br>• News redirect logic |
+
+For detailed initialization sequence and provider functions, see [app-startup-sequence.md](app-startup-sequence.md), if present.
+
+## Application Routes
+
+### Primary Apps
+- `/` → AppChat (default)
+- `/call` → Voice call interface
+- `/beam` → Multi-model reasoning
+- `/draw` → Image generation
+- `/personas` → Personas app
+- `/news` → News/updates
+
+### Zero States
+
+#### Chat App Zero States
+
+**CMLZeroModels**
+- **Location**: `/src/apps/chat/components/messages-list/CMLZeroModels.tsx`
+- **Triggered**: No LLM sources configured
+- **Shows**: Welcome screen with "Setup Models" button
+
+**CMLZeroConversation**
+- **Location**: `/src/apps/chat/components/messages-list/CMLZeroConversation.tsx`
+- **Triggered**: No conversation selected
+- **Shows**: "Select/create conversation" prompt
+
+**PersonaGrid**
+- **App**: Chat (when conversation is empty)
+- **Triggered**: Conversation exists but has no messages
+- **Shows**: Persona selector interface
+
+#### Feature-Specific Zero States
+
+**Beam Tutorial**
+- **Feature**: Beam (multi-model reasoning)
+- **Component**: `ExplainerCarousel`
+- **Triggered**: First-time Beam usage
+- **Shows**: Interactive feature walkthrough
+
+## Common Scenarios
+
+### New User First Visit
+1. Navigates to `/` → Provider stack loads
+2. Bootstrap runs → No news redirect (first visit)
+3. Chat loads → **CMLZeroModels** (no models configured)
+4. User clicks "Setup Models" → Configuration flow
+
+### Returning User with Saved State
+1. Navigates to `/` → Provider stack loads
+2. IndexedDB restores state → Previous conversation loaded
+3. Chat loads → **Active chat interface** (bypasses all zero states)
+4. All messages and context preserved from last session
+
+### Shared Chat Viewer
+1. Navigates to `/link/chat/[id]` → Full provider stack
+2. Views read-only chat → May see "Import" option
+3. If importing → Checks for duplicates, creates new local conversation
+
+## Storage System
+
+Big-AGI uses a local-first architecture:
+- **Zustand** for reactive state management
+- **IndexedDB** for persistent storage via Zustand persist middleware
+- **Version-based migrations** for data structure upgrades
+
+Key stores:
+- `app-chats`: Conversations and messages (IndexedDB)
+- `app-llms`: Model configurations (IndexedDB)
+- `app-ui`: UI preferences (localStorage)

next.config.mjs

@@ -1,70 +0,0 @@
-// Non-default build types
-const buildType =
-  process.env.BIG_AGI_BUILD === 'standalone' ? 'standalone'
-    : process.env.BIG_AGI_BUILD === 'static' ? 'export'
-      : undefined;
-
-buildType && console.log(`   🧠 big-AGI: building for ${buildType}...\n`);
-
-/** @type {import('next').NextConfig} */
-let nextConfig = {
-  reactStrictMode: true,
-
-  // [exports] https://nextjs.org/docs/advanced-features/static-html-export
-  ...buildType && {
-    output: buildType,
-    distDir: 'dist',
-
-    // disable image optimization for exports
-    images: { unoptimized: true },
-
-    // Optional: Change links `/me` -> `/me/` and emit `/me.html` -> `/me/index.html`
-    // trailingSlash: true,
-  },
-
-  // [puppeteer] https://github.com/puppeteer/puppeteer/issues/11052
-  experimental: {
-    serverComponentsExternalPackages: ['puppeteer-core'],
-  },
-
-  webpack: (config, _options) => {
-    // @mui/joy: anything material gets redirected to Joy
-    config.resolve.alias['@mui/material'] = '@mui/joy';
-
-    // @dqbd/tiktoken: enable asynchronous WebAssembly
-    config.experiments = {
-      asyncWebAssembly: true,
-      layers: true,
-    };
-
-    // prevent too many small chunks (40kb min) on 'client' packs (not 'server' or 'edge-server')
-    if (typeof config.optimization.splitChunks === 'object' && config.optimization.splitChunks.minSize)
-      config.optimization.splitChunks.minSize = 40 * 1024;
-
-    return config;
-  },
-
-  // Note: disabled to check whether the project becomes slower with this
-  // modularizeImports: {
-  //   '@mui/icons-material': {
-  //     transform: '@mui/icons-material/{{member}}',
-  //   },
-  // },
-
-  // Uncomment the following leave console messages in production
-  // compiler: {
-  //   removeConsole: false,
-  // },
-};
-
-// Validate environment variables, if set at build time. Will be actually read and used at runtime.
-// This is the reason both this file and the servr/env.mjs files have this extension.
-await import('./src/server/env.mjs');
-
-// conditionally enable the nextjs bundle analyzer
-if (process.env.ANALYZE_BUNDLE) {
-  const { default: withBundleAnalyzer } = await import('@next/bundle-analyzer');
-  nextConfig = withBundleAnalyzer({ openAnalyzer: true })(nextConfig);
-}
-
-export default nextConfig;

next.config.ts

@@ -0,0 +1,139 @@
+import type { NextConfig } from 'next';
+import { execSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+
+// Build information: from CI, or git commit hash
+let buildHash = process.env.NEXT_PUBLIC_BUILD_HASH || process.env.GITHUB_SHA || process.env.VERCEL_GIT_COMMIT_SHA; // Docker or custom, GitHub Actions, Vercel
+try {
+  // fallback to local git commit hash
+  if (!buildHash)
+    buildHash = execSync('git rev-parse --short HEAD').toString().trim();
+} catch {
+  // final fallback
+  buildHash = '2-dev';
+}
+// The following are used by/available to Release.buildInfo(...)
+process.env.NEXT_PUBLIC_BUILD_HASH = (buildHash || '').slice(0, 10);
+process.env.NEXT_PUBLIC_BUILD_PKGVER = JSON.parse('' + readFileSync(new URL('./package.json', import.meta.url))).version;
+process.env.NEXT_PUBLIC_BUILD_TIMESTAMP = new Date().toISOString();
+process.env.NEXT_PUBLIC_DEPLOYMENT_TYPE = process.env.NEXT_PUBLIC_DEPLOYMENT_TYPE || (process.env.VERCEL_ENV ? `vercel-${process.env.VERCEL_ENV}` : 'local'); // Docker or custom, Vercel
+console.log(` 🧠 \x1b[1mbig-AGI\x1b[0m v${process.env.NEXT_PUBLIC_BUILD_PKGVER} (@${process.env.NEXT_PUBLIC_BUILD_HASH})`);
+
+// Non-default build types
+const buildType =
+  process.env.BIG_AGI_BUILD === 'standalone' ? 'standalone' as const
+    : process.env.BIG_AGI_BUILD === 'static' ? 'export' as const
+      : undefined;
+
+buildType && console.log(` 🧠 big-AGI: building for ${buildType}...\n`);
+
+/** @type {import('next').NextConfig} */
+let nextConfig: NextConfig = {
+  reactStrictMode: true,
+
+  // [exports] https://nextjs.org/docs/advanced-features/static-html-export
+  ...(buildType && {
+    output: buildType,
+    distDir: 'dist',
+
+    // disable image optimization for exports
+    images: { unoptimized: true },
+
+    // Optional: Change links `/me` -> `/me/` and emit `/me.html` -> `/me/index.html`
+    // trailingSlash: true,
+  }),
+
+  // [puppeteer] https://github.com/puppeteer/puppeteer/issues/11052
+  // NOTE: we may not be needing this anymore, as we use '@cloudflare/puppeteer'
+  serverExternalPackages: ['puppeteer-core'],
+
+  webpack: (config: any, { isServer }: { isServer: boolean }) => {
+    // @mui/joy: anything material gets redirected to Joy
+    config.resolve.alias['@mui/material'] = '@mui/joy';
+
+    // @dqbd/tiktoken: enable asynchronous WebAssembly
+    config.experiments = {
+      asyncWebAssembly: true,
+      layers: true,
+    };
+
+    // fix warnings for async functions in the browser (https://github.com/vercel/next.js/issues/64792)
+    if (!isServer) {
+      config.output.environment = { ...config.output.environment, asyncFunction: true };
+    }
+
+    // prevent too many small chunks (40kb min) on 'client' packs (not 'server' or 'edge-server')
+    // noinspection JSUnresolvedReference
+    if (typeof config.optimization.splitChunks === 'object' && config.optimization.splitChunks.minSize) {
+      // noinspection JSUnresolvedReference
+      config.optimization.splitChunks.minSize = 40 * 1024;
+    }
+
+    return config;
+  },
+
+  // Optional Analytics > PostHog
+  skipTrailingSlashRedirect: true, // required to support PostHog trailing slash API requests
+  async rewrites() {
+    return [
+      {
+        source: '/a/ph/static/:path*',
+        destination: 'https://us-assets.i.posthog.com/static/:path*',
+      },
+      {
+        source: '/a/ph/:path*',
+        destination: 'https://us.i.posthog.com/:path*',
+      },
+      {
+        source: '/a/ph/decide',
+        destination: 'https://us.i.posthog.com/decide',
+      },
+      {
+        source: '/a/ph/flags',
+        destination: 'https://us.i.posthog.com/flags',
+      },
+    ];
+  },
+
+  // Note: disabled to check whether the project becomes slower with this
+  // modularizeImports: {
+  //   '@mui/icons-material': {
+  //     transform: '@mui/icons-material/{{member}}',
+  //   },
+  // },
+
+  // Uncomment the following leave console messages in production
+  // compiler: {
+  //   removeConsole: false,
+  // },
+};
+
+// Validate environment variables, if set at build time. Will be actually read and used at runtime.
+import { verifyBuildTimeVars } from '~/server/env';
+verifyBuildTimeVars();
+
+// PostHog error reporting with source maps for production builds
+import { withPostHogConfig } from '@posthog/nextjs-config';
+if (process.env.POSTHOG_API_KEY && process.env.POSTHOG_ENV_ID) {
+  console.log(' 🧠 \x1b[1mbig-AGI\x1b[0m: building with PostHog issue reporting and source maps...');
+  nextConfig = withPostHogConfig(nextConfig, {
+    personalApiKey: process.env.POSTHOG_API_KEY,
+    envId: process.env.POSTHOG_ENV_ID,
+    host: 'https://us.i.posthog.com', // backtrace upload host
+    verbose: false,
+    sourcemaps: {
+      enabled: process.env.NODE_ENV === 'production',
+      project: 'big-agi',
+      version: process.env.NEXT_PUBLIC_BUILD_HASH,
+      deleteAfterUpload: false, // false: leave them in the tree, which would also help debugging of open-source installs
+    },
+  });
+}
+
+// conditionally enable the nextjs bundle analyzer
+import withBundleAnalyzer from '@next/bundle-analyzer';
+if (process.env.ANALYZE_BUNDLE) {
+  nextConfig = withBundleAnalyzer({ openAnalyzer: true })(nextConfig) as NextConfig;
+}
+
+export default nextConfig;

package.json

@@ -1,15 +1,17 @@
 {
   "name": "big-agi",
-  "version": "1.15.1",
+  "version": "2.0.0",
   "private": true,
   "author": "Enrico Ros <enrico.ros@gmail.com>",
   "repository": "https://github.com/enricoros/big-agi",
   "scripts": {
-    "dev": "next dev",
+    "dev": "next dev --turbopack",
+    "dev-debug": "cross-env NODE_OPTIONS='--inspect' next dev",
+    "dev-https": "next dev --experimental-https",
     "build": "next build",
     "start": "next start",
     "lint": "next lint",
-    "postinstall": "prisma generate",
+    "postinstall": "prisma generate --no-hints",
     "db:push": "prisma db push",
     "db:studio": "prisma studio",
     "vercel:env:pull": "npx vercel env pull .env.development.local"
@@ -18,70 +20,78 @@
     "schema": "src/server/prisma/schema.prisma"
   },
   "dependencies": {
-    "@emotion/cache": "^11.11.0",
-    "@emotion/react": "^11.11.4",
+    "@dnd-kit/core": "^6.3.1",
+    "@dnd-kit/modifiers": "^9.0.0",
+    "@dnd-kit/sortable": "^10.0.0",
+    "@dnd-kit/utilities": "^3.2.2",
+    "@emotion/cache": "^11.14.0",
+    "@emotion/react": "^11.14.0",
     "@emotion/server": "^11.11.0",
-    "@emotion/styled": "^11.11.5",
-    "@mui/icons-material": "^5.15.15",
-    "@mui/joy": "^5.0.0-beta.32",
-    "@next/bundle-analyzer": "^14.1.4",
-    "@next/third-parties": "^14.2.0-canary.60",
-    "@prisma/client": "^5.12.1",
-    "@sanity/diff-match-patch": "^3.1.1",
-    "@t3-oss/env-nextjs": "^0.9.2",
-    "@tanstack/react-query": "~4.36.1",
-    "@trpc/client": "10.44.1",
-    "@trpc/next": "10.44.1",
-    "@trpc/react-query": "10.44.1",
-    "@trpc/server": "10.44.1",
-    "@vercel/analytics": "^1.2.2",
-    "@vercel/speed-insights": "^1.0.10",
-    "browser-fs-access": "^0.35.0",
-    "eventsource-parser": "^1.1.2",
-    "idb-keyval": "^6.2.1",
-    "next": "^14.1.4",
+    "@emotion/styled": "^11.14.1",
+    "@mui/icons-material": "^5.18.0",
+    "@mui/joy": "^5.0.0-beta.52",
+    "@next/bundle-analyzer": "~15.1.8",
+    "@prisma/client": "~5.22.0",
+    "@tanstack/react-query": "5.90.3",
+    "@trpc/client": "11.5.1",
+    "@trpc/next": "11.5.1",
+    "@trpc/react-query": "11.5.1",
+    "@trpc/server": "11.5.1",
+    "@vercel/analytics": "^1.5.0",
+    "@vercel/speed-insights": "^1.2.0",
+    "browser-fs-access": "^0.38.0",
+    "cheerio": "^1.1.2",
+    "csv-stringify": "^6.6.0",
+    "dexie": "^4.0.11",
+    "dexie-react-hooks": "^1.1.7",
+    "diff": "^8.0.2",
+    "eventemitter3": "^5.0.1",
+    "idb-keyval": "^6.2.2",
+    "mammoth": "^1.11.0",
+    "nanoid": "^5.1.6",
+    "next": "~15.1.8",
     "nprogress": "^0.2.0",
-    "pdfjs-dist": "4.0.379",
-    "plantuml-encoder": "^1.4.0",
-    "prismjs": "^1.29.0",
-    "react": "^18.2.0",
-    "react-beautiful-dnd": "^13.1.1",
-    "react-csv": "^2.2.2",
-    "react-dom": "^18.2.0",
-    "react-katex": "^3.0.1",
-    "react-markdown": "^9.0.1",
-    "react-player": "^2.15.1",
-    "react-resizable-panels": "^2.0.16",
-    "react-timeago": "^7.2.0",
-    "remark-gfm": "^4.0.0",
-    "sharp": "^0.33.3",
-    "superjson": "^2.2.1",
-    "tesseract.js": "^5.0.5",
-    "tiktoken": "^1.0.13",
-    "uuid": "^9.0.1",
-    "zod": "^3.22.4",
-    "zustand": "^4.5.2"
+    "pdfjs-dist": "5.4.54",
+    "posthog-js": "^1.275.3",
+    "posthog-node": "^5.10.0",
+    "prismjs": "^1.30.0",
+    "puppeteer-core": "^24.25.0",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "react-hook-form": "^7.65.0",
+    "react-markdown": "^10.1.0",
+    "react-player": "^3.3.3",
+    "react-resizable-panels": "^3.0.6",
+    "react-timeago": "^8.3.0",
+    "rehype-katex": "^7.0.1",
+    "remark-gfm": "^4.0.1",
+    "remark-mark-highlight": "^0.1.1",
+    "remark-math": "^6.0.0",
+    "sharp": "^0.33.5",
+    "superjson": "^2.2.2",
+    "tesseract.js": "^6.0.1",
+    "tiktoken": "^1.0.22",
+    "turndown": "^7.2.1",
+    "zod": "^4.1.12",
+    "zustand": "5.0.7"
   },
   "devDependencies": {
-    "@cloudflare/puppeteer": "0.0.5",
-    "@types/node": "^20.12.5",
+    "@posthog/nextjs-config": "^1.3.2",
+    "@types/node": "^24.7.2",
     "@types/nprogress": "^0.2.3",
-    "@types/plantuml-encoder": "^1.4.2",
-    "@types/prismjs": "^1.26.3",
-    "@types/react": "^18.2.74",
-    "@types/react-beautiful-dnd": "^13.1.8",
+    "@types/prismjs": "^1.26.5",
+    "@types/react": "^19.2.2",
     "@types/react-csv": "^1.1.10",
-    "@types/react-dom": "^18.2.24",
-    "@types/react-katex": "^3.0.4",
-    "@types/react-timeago": "^4.1.7",
-    "@types/uuid": "^9.0.8",
-    "eslint": "^8.57.0",
-    "eslint-config-next": "^14.1.4",
-    "prettier": "^3.2.5",
-    "prisma": "^5.12.1",
-    "typescript": "^5.4.4"
+    "@types/react-dom": "^19.2.2",
+    "@types/turndown": "^5.0.5",
+    "cross-env": "^10.1.0",
+    "eslint": "^9.37.0",
+    "eslint-config-next": "~15.1.8",
+    "prettier": "^3.6.2",
+    "prisma": "~5.22.0",
+    "typescript": "^5.9.3"
   },
   "engines": {
-    "node": "^20.0.0 || ^18.0.0"
+    "node": "^26.0.0 || ^24.0.0 || ^22.0.0 || ^20.0.0"
   }
 }

pages/_app.tsx

@@ -11,20 +11,29 @@ import 'katex/dist/katex.min.css';
 import '~/common/styles/CodePrism.css';
 import '~/common/styles/GithubMarkdown.css';
 import '~/common/styles/NProgress.css';
+import '~/common/styles/agi.effects.css';
 import '~/common/styles/app.styles.css';
 
+import { ErrorBoundary } from '~/common/components/ErrorBoundary';
+import { Is } from '~/common/util/pwaUtils';
+import { OverlaysInsert } from '~/common/layout/overlays/OverlaysInsert';
 import { ProviderBackendCapabilities } from '~/common/providers/ProviderBackendCapabilities';
 import { ProviderBootstrapLogic } from '~/common/providers/ProviderBootstrapLogic';
 import { ProviderSingleTab } from '~/common/providers/ProviderSingleTab';
-import { ProviderSnacks } from '~/common/providers/ProviderSnacks';
-import { ProviderTRPCQuerySettings } from '~/common/providers/ProviderTRPCQuerySettings';
 import { ProviderTheming } from '~/common/providers/ProviderTheming';
-import { hasGoogleAnalytics, OptionalGoogleAnalytics } from '~/common/components/GoogleAnalytics';
-import { isVercelFromFrontend } from '~/common/util/pwaUtils';
+import { SnackbarInsert } from '~/common/components/snackbar/SnackbarInsert';
+import { hasGoogleAnalytics, OptionalGoogleAnalytics } from '~/common/components/3rdparty/GoogleAnalytics';
+import { hasPostHogAnalytics, OptionalPostHogAnalytics } from '~/common/components/3rdparty/PostHogAnalytics';
 
 
-const MyApp = ({ Component, emotionCache, pageProps }: MyAppProps) =>
-  <>
+const Big_AGI_App = ({ Component, emotionCache, pageProps }: MyAppProps) => {
+
+  // We are using a nextjs per-page layout pattern to bring the (Optima) layout creation to a shared place
+  // This reduces the flicker and the time switching between apps, and seems to not have impact on
+  // the build. This is a good trade-off for now.
+  const getLayout = Component.getLayout ?? ((page: any) => page);
+
+  return <>
 
     <Head>
       <title>{Brand.Title.Common}</title>
@@ -33,24 +42,26 @@ const MyApp = ({ Component, emotionCache, pageProps }: MyAppProps) =>
 
     <ProviderTheming emotionCache={emotionCache}>
       <ProviderSingleTab>
-        <ProviderTRPCQuerySettings>
-          <ProviderBackendCapabilities>
-            {/* ^ SSR boundary */}
+        <ProviderBackendCapabilities>
+          {/* ^ Backend capabilities & SSR boundary */}
+          <ErrorBoundary outer>
             <ProviderBootstrapLogic>
-              <ProviderSnacks>
-                <Component {...pageProps} />
-              </ProviderSnacks>
+              <SnackbarInsert />
+              {getLayout(<Component {...pageProps} />)}
+              <OverlaysInsert />
             </ProviderBootstrapLogic>
-          </ProviderBackendCapabilities>
-        </ProviderTRPCQuerySettings>
+          </ErrorBoundary>
+        </ProviderBackendCapabilities>
       </ProviderSingleTab>
     </ProviderTheming>
 
-    {isVercelFromFrontend && <VercelAnalytics debug={false} />}
-    {isVercelFromFrontend && <VercelSpeedInsights debug={false} sampleRate={1 / 2} />}
+    {Is.Deployment.VercelFromFrontend && <VercelAnalytics debug={false} />}
+    {Is.Deployment.VercelFromFrontend && <VercelSpeedInsights debug={false} sampleRate={1 / 2} />}
     {hasGoogleAnalytics && <OptionalGoogleAnalytics />}
+    {hasPostHogAnalytics && <OptionalPostHogAnalytics />}
 
   </>;
+};
 
-// enables the React Query API invocation
-export default apiQuery.withTRPC(MyApp);
+// Initializes React Query and tRPC, and enables the tRPC React Query hooks (apiQuery).
+export default apiQuery.withTRPC(Big_AGI_App);

pages/_document.tsx

@@ -2,7 +2,7 @@ import * as React from 'react';
 import { AppType, MyAppProps } from 'next/app';
 import { default as Document, DocumentContext, DocumentProps, Head, Html, Main, NextScript } from 'next/document';
 import createEmotionServer from '@emotion/server/create-instance';
-import { getInitColorSchemeScript } from '@mui/joy/styles';
+import InitColorSchemeScript from '@mui/joy/InitColorSchemeScript';
 
 import { Brand } from '~/common/app.config';
 import { createEmotionCache } from '~/common/app.theme';
@@ -51,7 +51,7 @@ export default function MyDocument({ emotionStyleTags }: MyDocumentProps) {
         {emotionStyleTags}
       </Head>
       <body>
-      {getInitColorSchemeScript()}
+      <InitColorSchemeScript />
       <Main />
       <NextScript />
       </body>
@@ -100,6 +100,10 @@ MyDocument.getInitialProps = async (ctx: DocumentContext) => {
     });
 
   const initialProps = await Document.getInitialProps(ctx);
+
+  // Inject the comment before the HTML tag
+  initialProps.html = `<!-- ❤ Built with Big-AGI -->\n${initialProps.html}`;
+
   // This is important. It prevents Emotion to render invalid HTML.
   // See https://github.com/mui/material-ui/issues/26561#issuecomment-855286153
   const emotionStyles = extractCriticalToChunks(initialProps.html);

pages/call.tsx

@@ -2,9 +2,7 @@ import * as React from 'react';
 
 import { AppCall } from '../src/apps/call/AppCall';
 
-import { withLayout } from '~/common/layout/withLayout';
+import { withNextJSPerPageLayout } from '~/common/layout/withLayout';
 
 
-export default function CallPage() {
-  return withLayout({ type: 'optima' }, <AppCall />);
-}
+export default withNextJSPerPageLayout({ type: 'optima' }, () => <AppCall />);

pages/dev/beam.tsx

@@ -2,9 +2,7 @@ import * as React from 'react';
 
 import { AppBeam } from '../../src/apps/beam/AppBeam';
 
-import { withLayout } from '~/common/layout/withLayout';
+import { withNextJSPerPageLayout } from '~/common/layout/withLayout';
 
 
-export default function BeamPage() {
-  return withLayout({ type: 'optima' }, <AppBeam />);
-}
+export default withNextJSPerPageLayout({ type: 'optima' }, () => <AppBeam />);

pages/diff.tsx

@@ -0,0 +1,8 @@
+import * as React from 'react';
+
+import { AppDiff } from '../src/apps/diff/AppDiff';
+
+import { withNextJSPerPageLayout } from '~/common/layout/withLayout';
+
+
+export default withNextJSPerPageLayout({ type: 'optima' }, () => <AppDiff />);

pages/draw.tsx

@@ -2,9 +2,7 @@ import * as React from 'react';
 
 import { AppDraw } from '../src/apps/draw/AppDraw';
 
-import { withLayout } from '~/common/layout/withLayout';
+import { withNextJSPerPageLayout } from '~/common/layout/withLayout';
 
 
-export default function DrawPage() {
-  return withLayout({ type: 'optima' }, <AppDraw />);
-}
+export default withNextJSPerPageLayout({ type: 'optima' }, () => <AppDraw />);

pages/index.tsx

@@ -2,13 +2,13 @@ import * as React from 'react';
 
 import { AppChat } from '../src/apps/chat/AppChat';
 
-import { withLayout } from '~/common/layout/withLayout';
+import { withNextJSPerPageLayout } from '~/common/layout/withLayout';
 
 
-export default function IndexPage() {
+export default withNextJSPerPageLayout({ type: 'optima' }, () => {
 
   // TODO: This Index page will point to the Dashboard (or a landing page)
   // For now it offers the chat experience, but this will change. #299
 
-  return withLayout({ type: 'optima' }, <AppChat />);
-}
+  return <AppChat />;
+});

pages/info/debug.tsx

@@ -7,31 +7,29 @@ import DownloadIcon from '@mui/icons-material/Download';
 import { AppPlaceholder } from '../../src/apps/AppPlaceholder';
 
 import { getBackendCapabilities } from '~/modules/backend/store-backend-capabilities';
-import { getPlantUmlServerUrl } from '~/modules/blocks/code/RenderCode';
+import { getPlantUmlServerUrl } from '~/modules/blocks/code/code-renderers/RenderCodePlantUML';
 
-import { withLayout } from '~/common/layout/withLayout';
+import { withNextJSPerPageLayout } from '~/common/layout/withLayout';
 
 
-// app config
+// basics
 import { Brand } from '~/common/app.config';
 import { ROUTE_APP_CHAT, ROUTE_INDEX } from '~/common/app.routes';
-
-// apps access
-import { incrementalNewsVersion } from '../../src/apps/news/news.version';
+import { Release } from '~/common/app.release';
 
 // capabilities access
 import { useCapabilityBrowserSpeechRecognition, useCapabilityElevenLabs, useCapabilityTextToImage } from '~/common/components/useCapabilities';
 
 // stores access
-import { getLLMsDebugInfo } from '~/modules/llms/store-llms';
-import { useAppStateStore } from '~/common/state/store-appstate';
-import { useChatStore } from '~/common/state/store-chats';
-import { useFolderStore } from '~/common/state/store-folders';
-import { useUXLabsStore } from '~/common/state/store-ux-labs';
+import { getLLMsDebugInfo } from '~/common/stores/llms/store-llms';
+import { useChatStore } from '~/common/stores/chat/store-chats';
+import { useFolderStore } from '~/common/stores/folders/store-chat-folders';
+import { useLogicSherpaStore } from '~/common/logic/store-logic-sherpa';
+import { useUXLabsStore } from '~/common/stores/store-ux-labs';
 
 // utils access
-import { clientHostName, isChromeDesktop, isFirefox, isIPhoneUser, isMacUser, isPwa, isVercelFromFrontend } from '~/common/util/pwaUtils';
-import { getGA4MeasurementId } from '~/common/components/GoogleAnalytics';
+import { BrowserLang, clientHostName, Is, isPwa } from '~/common/util/pwaUtils';
+import { getGA4MeasurementId } from '~/common/components/3rdparty/GoogleAnalytics';
 import { prettyTimestampForFilenames } from '~/common/util/timeUtils';
 import { supportsClipboardRead } from '~/common/util/clipboardUtils';
 import { supportsScreenCapture } from '~/common/util/screenCaptureUtils';
@@ -71,6 +69,8 @@ function DebugJsonCard(props: { title: string, data: any }) {
 }
 
 
+const frontendBuild = Release.buildInfo('frontend');
+
 function AppDebug() {
 
   // state
@@ -81,18 +81,15 @@ function AppDebug() {
   const chatsCount = useChatStore.getState().conversations?.length;
   const uxLabsExperiments = Object.entries(useUXLabsStore.getState()).filter(([_k, v]) => v === true).map(([k, _]) => k).join(', ');
   const { folders, enableFolders } = useFolderStore.getState();
-  const { lastSeenNewsVersion, usageCount } = useAppStateStore.getState();
-
+  const { lastSeenNewsVersion, usageCount } = useLogicSherpaStore.getState();
 
   // derived state
   const cClient = {
     // isBrowser,
-    isChromeDesktop,
-    isFirefox,
-    isIPhone: isIPhoneUser,
-    isMac: isMacUser,
+    Is,
+    BrowserLang,
     isPWA: isPwa(),
-    supportsClipboardPaste: supportsClipboardRead,
+    supportsClipboardPaste: supportsClipboardRead(),
     supportsScreenCapture,
   };
   const cProduct = {
@@ -106,18 +103,20 @@ function AppDebug() {
       chatsCount,
       foldersCount: folders?.length,
       foldersEnabled: enableFolders,
-      newsCurrent: incrementalNewsVersion,
+      newsCurrent: Release.Monotonics.NewsVersion,
       newsSeen: lastSeenNewsVersion,
       labsActive: uxLabsExperiments,
       reloads: usageCount,
     },
+    release: {
+      build: frontendBuild,
+    },
   };
   const cBackend = {
     configuration: backendCaps,
     deployment: {
       home: Brand.URIs.Home,
       hostName: clientHostName(),
-      isVercelFromFrontend,
       measurementId: getGA4MeasurementId(),
       plantUmlServerUrl: getPlantUmlServerUrl(),
       routeIndex: ROUTE_INDEX,
@@ -163,6 +162,4 @@ function AppDebug() {
 }
 
 
-export default function DebugPage() {
-  return withLayout({ type: 'plain' }, <AppDebug />);
-};
+export default withNextJSPerPageLayout({ type: 'container' }, () => <AppDebug />);

pages/link/callback_openrouter.tsx

@@ -2,20 +2,19 @@ import * as React from 'react';
 
 import { Box, Typography } from '@mui/joy';
 
-import { useModelsStore } from '~/modules/llms/store-llms';
+import { llmsStoreActions } from '~/common/stores/llms/store-llms';
 
 import { InlineError } from '~/common/components/InlineError';
 import { apiQuery } from '~/common/util/trpc.client';
 import { navigateToIndex, useRouterQuery } from '~/common/app.routes';
-import { withLayout } from '~/common/layout/withLayout';
+import { withNextJSPerPageLayout } from '~/common/layout/withLayout';
 
 
 function CallbackOpenRouterPage(props: { openRouterCode: string | undefined }) {
 
   // external state
-  const { data, isError, error, isLoading } = apiQuery.backend.exchangeOpenRouterKey.useQuery({ code: props.openRouterCode || '' }, {
+  const { data, isError, error, isPending } = apiQuery.backend.exchangeOpenRouterKey.useQuery({ code: props.openRouterCode || '' }, {
     enabled: !!props.openRouterCode,
-    refetchOnWindowFocus: false,
     staleTime: Infinity,
   });
 
@@ -31,7 +30,7 @@ function CallbackOpenRouterPage(props: { openRouterCode: string | undefined }) {
       return;
 
     // 1. Save the key as the client key
-    useModelsStore.getState().setOpenRoutersKey(openRouterKey);
+    llmsStoreActions().setOpenRouterKey(openRouterKey);
 
     // 2. Navigate to the chat app
     void navigateToIndex(true); //.then(openModelsSetup);
@@ -56,7 +55,7 @@ function CallbackOpenRouterPage(props: { openRouterCode: string | undefined }) {
           Welcome Back
         </Typography>
 
-        {isLoading && <Typography level='body-sm'>Loading...</Typography>}
+        {isPending && <Typography level='body-sm'>Loading...</Typography>}
 
         {isErrorInput && <InlineError error='There was an issue retrieving the code from OpenRouter.' />}
 
@@ -81,10 +80,11 @@ function CallbackOpenRouterPage(props: { openRouterCode: string | undefined }) {
  * Docs: https://openrouter.ai/docs#oauth
  * Example URL: https://localhost:3000/link/callback_openrouter?code=SomeCode
  */
-export default function CallbackPage() {
+export default withNextJSPerPageLayout({ type: 'container' }, () => {
 
   // external state - get the 'code=...' from the URL
   const { code } = useRouterQuery<{ code: string | undefined }>();
 
-  return withLayout({ type: 'plain' }, <CallbackOpenRouterPage openRouterCode={code} />);
-}
+  return <CallbackOpenRouterPage openRouterCode={code} />;
+
+});

pages/link/chat/[chatLinkId].tsx

@@ -3,13 +3,14 @@ import * as React from 'react';
 import { AppLinkChat } from '../../../src/apps/link-chat/AppLinkChat';
 
 import { useRouterQuery } from '~/common/app.routes';
-import { withLayout } from '~/common/layout/withLayout';
+import { withNextJSPerPageLayout } from '~/common/layout/withLayout';
 
 
-export default function ChatLinkPage() {
+export default withNextJSPerPageLayout({ type: 'optima', suspendAutoModelsSetup: true }, () => {
 
   // external state
   const { chatLinkId } = useRouterQuery<{ chatLinkId: string | undefined }>();
 
-  return withLayout({ type: 'optima', suspendAutoModelsSetup: true }, <AppLinkChat chatLinkId={chatLinkId || null} />);
-}
+  return <AppLinkChat chatLinkId={chatLinkId || null} />;
+
+});

pages/link/share_target.tsx

@@ -3,14 +3,14 @@ import * as React from 'react';
 import { Alert, Box, Button, Typography } from '@mui/joy';
 import ArrowBackIcon from '@mui/icons-material/ArrowBack';
 
-import { setComposerStartupText } from '../../src/apps/chat/components/composer/store-composer';
+import { setComposerStartupText } from '~/common/logic/store-logic-sherpa';
 
-import { callBrowseFetchPage } from '~/modules/browse/browse.client';
+import { callBrowseFetchPageOrThrow } from '~/modules/browse/browse.client';
 
 import { LogoProgress } from '~/common/components/LogoProgress';
 import { asValidURL } from '~/common/util/urlUtils';
 import { navigateToIndex, useRouterQuery } from '~/common/app.routes';
-import { withLayout } from '~/common/layout/withLayout';
+import { withNextJSPerPageLayout } from '~/common/layout/withLayout';
 
 
 /**
@@ -75,11 +75,18 @@ function AppShareTarget() {
   React.useEffect(() => {
     if (intentURL) {
       setIsDownloading(true);
-      callBrowseFetchPage(intentURL)
+      callBrowseFetchPageOrThrow(intentURL)
         .then(page => {
-          if (page.stopReason !== 'error')
-            queueComposerTextAndLaunchApp('\n\n```' + intentURL + '\n' + page.content + '\n```\n');
-          else
+          if (page.stopReason !== 'error') {
+            if (!page.content) {
+              setErrorMessage(page.file ? 'No web page found, and we do not support files at the moment.' : 'No content found');
+              return;
+            }
+            let pageContent = page.content.markdown || page.content.text || page.content.html || '';
+            if (pageContent)
+              pageContent = '\n\n```' + intentURL + '\n' + pageContent + '\n```\n';
+            queueComposerTextAndLaunchApp(pageContent);
+          } else
             setErrorMessage('Could not read any data' + page.error ? ': ' + page.error : '');
         })
         .catch(error => setErrorMessage(error?.message || error || 'Unknown error'))
@@ -132,6 +139,4 @@ function AppShareTarget() {
  * This page will be invoked on mobile when sharing Text/URLs/Files from other APPs
  * Example URL: https://localhost:3000/link/share_target?title=This+Title&text=https%3A%2F%2Fexample.com%2Fapp%2Fpath
  */
-export default function ShareTargetPage() {
-  return withLayout({ type: 'plain' }, <AppShareTarget />);
-}
+export default withNextJSPerPageLayout({ type: 'container' }, () => <AppShareTarget />);

pages/news.tsx

@@ -1,14 +1,15 @@
 import * as React from 'react';
 
 import { AppNews } from '../src/apps/news/AppNews';
-import { markNewsAsSeen } from '../src/apps/news/news.version';
 
-import { withLayout } from '~/common/layout/withLayout';
+import { markNewsAsSeen } from '~/common/logic/store-logic-sherpa';
+import { withNextJSPerPageLayout } from '~/common/layout/withLayout';
 
 
-export default function NewsPage() {
+export default withNextJSPerPageLayout({ type: 'optima', suspendAutoModelsSetup: true }, () => {
+
   // 'touch' the last seen news version
   React.useEffect(() => markNewsAsSeen(), []);
 
-  return withLayout({ type: 'optima', suspendAutoModelsSetup: true }, <AppNews />);
-}
+  return <AppNews />;
+});

pages/personas.tsx

@@ -2,9 +2,7 @@ import * as React from 'react';
 
 import { AppPersonas } from '../src/apps/personas/AppPersonas';
 
-import { withLayout } from '~/common/layout/withLayout';
+import { withNextJSPerPageLayout } from '~/common/layout/withLayout';
 
 
-export default function PersonasPage() {
-  return withLayout({ type: 'optima' }, <AppPersonas />);
-}
+export default withNextJSPerPageLayout({ type: 'optima' }, () => <AppPersonas />);

pages/tokens.tsx

@@ -0,0 +1,8 @@
+import * as React from 'react';
+
+import { AppTokens } from '../src/apps/tokens/AppTokens';
+
+import { withNextJSPerPageLayout } from '~/common/layout/withLayout';
+
+
+export default withNextJSPerPageLayout({ type: 'optima' }, () => <AppTokens />);

pages/workspace.tsx

@@ -1,12 +1,8 @@
 import * as React from 'react';
 
-import { Box } from '@mui/joy';
+import { AppPlaceholder } from '../src/apps/AppPlaceholder';
 
-// import { AppWorkspace } from '../src/apps/personas/AppWorkspace';
-
-import { withLayout } from '~/common/layout/withLayout';
+import { withNextJSPerPageLayout } from '~/common/layout/withLayout';
 
 
-export default function PersonasPage() {
-  return withLayout({ type: 'optima' }, <Box />);
-}
+export default withNextJSPerPageLayout({ type: 'optima' }, () => <AppPlaceholder />);

public/manifest.json

@@ -11,24 +11,26 @@
     "utilities"
   ],
   "display": "standalone",
-  "start_url": "/",
+  "start_url": "/?source=pwa",
   "scope": "/",
   "icons": [
     {
-      "src": "/icons/icon-192x192.png",
-      "sizes": "192x192",
+      "src": "/icons/icon-1024x1024.png",
+      "sizes": "1024x1024",
       "type": "image/png",
-      "purpose": "maskable"
+      "purpose": "any maskable"
     },
     {
       "src": "/icons/icon-512x512.png",
       "sizes": "512x512",
-      "type": "image/png"
+      "type": "image/png",
+      "purpose": "any"
     },
     {
-      "src": "/icons/icon-1024x1024.png",
-      "sizes": "1024x1024",
-      "type": "image/png"
+      "src": "/icons/icon-192x192.png",
+      "sizes": "192x192",
+      "type": "image/png",
+      "purpose": "any"
     }
   ],
   "file_handlers": [
@@ -51,5 +53,31 @@
       "text": "text",
       "url": "url"
     }
-  }
+  },
+  "shortcuts": [
+    {
+      "name": "Call",
+      "url": "/call",
+      "description": "Call a Persona",
+      "icons": [
+        {
+          "src": "/icons/icon-call-96x96.png",
+          "sizes": "96x96",
+          "type": "image/png"
+        }
+      ]
+    },
+    {
+      "name": "New Voice Chat",
+      "url": "/?newChat=voiceInput",
+      "description": "Start a new chat with voice input",
+      "icons": [
+        {
+          "src": "/icons/icon-voicechat-96x96.png",
+          "sizes": "96x96",
+          "type": "image/png"
+        }
+      ]
+    }
+  ]
 }

src/apps/AppSmallContainer.tsx

@@ -0,0 +1,27 @@
+import * as React from 'react';
+
+import { Box, Container, Typography } from '@mui/joy';
+
+
+export function AppSmallContainer({ title, description, children }: {
+  title: string;
+  description: React.ReactNode;
+  children: React.ReactNode;
+}) {
+  return (
+    <Box sx={{ flexGrow: 1, overflowY: 'auto', p: { xs: 3, md: 6 } }}>
+
+      <Container disableGutters maxWidth='md' sx={{ display: 'flex', flexDirection: 'column', gap: 3 }}>
+
+        <Box sx={{ mb: 2 }}>
+          <Typography level='h1' sx={{ mb: 1 }}>{title}</Typography>
+          <Typography>{description}</Typography>
+        </Box>
+
+        {children}
+
+      </Container>
+
+    </Box>
+  );
+}

src/apps/beam/AppBeam.tsx

@@ -5,23 +5,23 @@ import { Box, Button, Typography } from '@mui/joy';
 
 import { BeamStoreApi, useBeamStore } from '~/modules/beam/store-beam.hooks';
 import { BeamView } from '~/modules/beam/BeamView';
-import { createBeamVanillaStore } from '~/modules/beam/store-beam-vanilla';
-import { useModelsStore } from '~/modules/llms/store-llms';
+import { createBeamVanillaStore } from '~/modules/beam/store-beam_vanilla';
 
-import { createDConversation, createDMessage, DConversation, DMessage } from '~/common/state/store-chats';
+import { OptimaToolbarIn } from '~/common/layout/optima/portals/OptimaPortalsIn';
+import { createDConversation, DConversation } from '~/common/stores/chat/chat.conversation';
+import { createDMessageTextContent, DMessage } from '~/common/stores/chat/chat.message';
 import { useIsMobile } from '~/common/components/useMatchMedia';
-import { usePluggableOptimaLayout } from '~/common/layout/optima/useOptimaLayout';
 
 
 function initTestConversation(): DConversation {
   const conversation = createDConversation();
-  conversation.messages.push(createDMessage('system', 'You are a helpful assistant.'));
-  conversation.messages.push(createDMessage('user', 'Hello, who are you? (please expand...)'));
+  conversation.messages.push(createDMessageTextContent('system', 'You are a helpful assistant.')); // Beam Test - seed1
+  conversation.messages.push(createDMessageTextContent('user', 'Hello, who are you? (please expand...)')); // Beam Test - seed2
   return conversation;
 }
 
 function initTestBeamStore(messages: DMessage[], beamStore: BeamStoreApi = createBeamVanillaStore()): BeamStoreApi {
-  beamStore.getState().open(messages, useModelsStore.getState().chatLLMId, (text) => alert(text));
+  beamStore.getState().open(messages, null, false, (content) => alert(content));
   return beamStore;
 }
 
@@ -30,8 +30,16 @@ export function AppBeam() {
 
   // state
   const [showDebug, setShowDebug] = React.useState(false);
-  const conversation = React.useRef<DConversation>(initTestConversation());
-  const beamStoreApi = React.useRef(initTestBeamStore(conversation.current.messages)).current;
+
+  const [conversation, setConversation] = React.useState<DConversation>(() => initTestConversation());
+  const [beamStoreApi] = React.useState(() => createBeamVanillaStore());
+
+
+  // reinit the beam store if the conversation changes
+  React.useEffect(() => {
+    initTestBeamStore(conversation.messages, beamStoreApi);
+  }, [beamStoreApi, conversation]);
+
 
   // external state
   const isMobile = useIsMobile();
@@ -44,22 +52,18 @@ export function AppBeam() {
 
 
   const handleClose = React.useCallback(() => {
-    beamStoreApi.getState().terminate();
+    beamStoreApi.getState().terminateKeepingSettings();
   }, [beamStoreApi]);
 
 
-  // layout
-  usePluggableOptimaLayout(null, React.useMemo(() => <>
+  const toolbarItems = React.useMemo(() => <>
     {/* button to toggle debug info */}
     <Button size='sm' variant='plain' color='neutral' onClick={() => setShowDebug(on => !on)}>
       {showDebug ? 'Hide' : 'Show'} debug
     </Button>
 
     {/* 'open' */}
-    <Button size='sm' variant='plain' color='neutral' onClick={() => {
-      conversation.current = initTestConversation();
-      initTestBeamStore(conversation.current.messages, beamStoreApi);
-    }}>
+    <Button size='sm' variant='plain' color='neutral' onClick={() => setConversation(initTestConversation())}>
       .open
     </Button>
 
@@ -67,10 +71,12 @@ export function AppBeam() {
     <Button size='sm' variant='plain' color='neutral' onClick={handleClose}>
       .close
     </Button>
-  </>, [beamStoreApi, handleClose, showDebug]), null, 'AppBeam');
+  </>, [handleClose, showDebug]);
 
 
-  return (
+  return <>
+    <OptimaToolbarIn>{toolbarItems}</OptimaToolbarIn>
+
     <Box sx={{ flexGrow: 1, overflowY: 'auto', position: 'relative' }}>
 
       {isOpen && (
@@ -96,5 +102,6 @@ export function AppBeam() {
       )}
 
     </Box>
-  );
+
+  </>;
 }

src/apps/call/AppCall.tsx

@@ -2,7 +2,7 @@ import * as React from 'react';
 
 import { Container, Sheet } from '@mui/joy';
 
-import type { DConversationId } from '~/common/state/store-chats';
+import type { DConversationId } from '~/common/stores/chat/chat.conversation';
 import { useRouterQuery } from '~/common/app.routes';
 
 import { CallWizard } from './CallWizard';

src/apps/call/CallWizard.tsx

@@ -9,12 +9,12 @@ import MicIcon from '@mui/icons-material/Mic';
 import RecordVoiceOverTwoToneIcon from '@mui/icons-material/RecordVoiceOverTwoTone';
 import WarningRoundedIcon from '@mui/icons-material/WarningRounded';
 
-import { PreferencesTab, useOptimaLayout } from '~/common/layout/optima/useOptimaLayout';
 import { animationColorRainbow } from '~/common/util/animUtils';
 import { navigateBack } from '~/common/app.routes';
+import { optimaOpenPreferences } from '~/common/layout/optima/useOptima';
 import { useCapabilityBrowserSpeechRecognition, useCapabilityElevenLabs } from '~/common/components/useCapabilities';
-import { useChatStore } from '~/common/state/store-chats';
-import { useUICounter } from '~/common/state/store-ui';
+import { useChatStore } from '~/common/stores/chat/store-chats';
+import { useUICounter } from '~/common/stores/store-ui';
 
 
 function StatusCard(props: { icon: React.JSX.Element, hasIssue: boolean, text: string, button?: React.JSX.Element }) {
@@ -44,7 +44,6 @@ export function CallWizard(props: { strict?: boolean, conversationId: string | n
   const [recognitionOverride, setRecognitionOverride] = React.useState(false);
 
   // external state
-  const { openPreferencesTab } = useOptimaLayout();
   const recognition = useCapabilityBrowserSpeechRecognition();
   const synthesis = useCapabilityElevenLabs();
   const chatIsEmpty = useChatStore(state => {
@@ -62,22 +61,22 @@ export function CallWizard(props: { strict?: boolean, conversationId: string | n
   const allGood = overriddenEmptyChat && overriddenRecognition && synthesis.mayWork;
   const fatalGood = overriddenRecognition && synthesis.mayWork;
 
-  if (!novel && fatalGood)
-    return props.children;
 
-  const handleOverrideChatEmpty = () => setChatEmptyOverride(true);
+  const handleOverrideChatEmpty = React.useCallback(() => setChatEmptyOverride(true), []);
 
-  const handleOverrideRecognition = () => setRecognitionOverride(true);
+  const handleOverrideRecognition = React.useCallback(() => setRecognitionOverride(true), []);
 
-  const handleConfigureElevenLabs = () => {
-    openPreferencesTab(PreferencesTab.Voice);
-  };
+  const handleConfigureElevenLabs = React.useCallback(() => optimaOpenPreferences('voice'), []);
 
-  const handleFinishButton = () => {
+  const handleFinishButton = React.useCallback(() => {
     if (!allGood)
       return navigateBack();
     touch();
-  };
+  }, [allGood, touch]);
+
+
+  if (!novel && fatalGood)
+    return props.children;
 
 
   return <>

src/apps/call/Contacts.tsx

@@ -1,14 +1,15 @@
 import * as React from 'react';
-import { shallow } from 'zustand/shallow';
 
 import type { SxProps } from '@mui/joy/styles/types';
 import { Avatar, Box, Card, CardContent, Chip, IconButton, Link as MuiLink, ListDivider, MenuItem, Sheet, Switch, Typography } from '@mui/joy';
 import CallIcon from '@mui/icons-material/Call';
 
 import { GitHubProjectIssueCard } from '~/common/components/GitHubProjectIssueCard';
+import { OptimaPanelGroupedList } from '~/common/layout/optima/panel/OptimaPanelGroupedList';
+import { OptimaPanelIn } from '~/common/layout/optima/portals/OptimaPortalsIn';
 import { animationShadowRingLimey } from '~/common/util/animUtils';
-import { conversationTitle, DConversation, DConversationId, useChatStore } from '~/common/state/store-chats';
-import { usePluggableOptimaLayout } from '~/common/layout/optima/useOptimaLayout';
+import { conversationTitle, DConversation, DConversationId } from '~/common/stores/chat/chat.conversation';
+import { useChatStore } from '~/common/stores/chat/store-chats';
 
 import type { AppCallIntent } from './AppCall';
 import { MockPersona, useMockPersonas } from './state/useMockPersonas';
@@ -60,7 +61,7 @@ const ContactCardConversationCall = (props: { conversation: DConversation, onCon
 function CallContactCard(props: {
   persona: MockPersona,
   callGrayUI: boolean,
-  conversations: DConversation[],
+  conversations: Readonly<DConversation[]>,
   setCallIntent: (intent: AppCallIntent) => void,
 }) {
 
@@ -189,7 +190,7 @@ function CallContactCard(props: {
 
 
 function useConversationsByPersona() {
-  const conversations = useChatStore(state => state.conversations, shallow);
+  const conversations = useChatStore(state => state.conversations);
 
   return React.useMemo(() => {
     // group by personaId
@@ -209,7 +210,7 @@ function useConversationsByPersona() {
 }
 
 
-export function Contacts(props: { setCallIntent: (intent: AppCallIntent) => void }) {
+function ContactsMenuItems() {
 
   // external state
   const {
@@ -217,36 +218,43 @@ export function Contacts(props: { setCallIntent: (intent: AppCallIntent) => void
     showConversations, toggleShowConversations,
     showSupport, toggleShowSupport,
   } = useAppCallStore();
+
+  return (
+    <OptimaPanelGroupedList title='Contacts Settings'>
+
+      <MenuItem onClick={toggleGrayUI}>
+        Grayed UI
+        <Switch checked={grayUI} sx={{ ml: 'auto' }} />
+      </MenuItem>
+
+      <MenuItem onClick={toggleShowConversations}>
+        Conversations
+        <Switch checked={showConversations} sx={{ ml: 'auto' }} />
+      </MenuItem>
+
+      <MenuItem onClick={toggleShowSupport}>
+        Show Support
+        <Switch checked={showSupport} sx={{ ml: 'auto' }} />
+      </MenuItem>
+
+    </OptimaPanelGroupedList>
+  );
+}
+
+
+export function Contacts(props: { setCallIntent: (intent: AppCallIntent) => void }) {
+
+  // external state
   const { personas } = useMockPersonas();
+  const { grayUI, showConversations, showSupport } = useAppCallStore();
   const conversationsByPersona = useConversationsByPersona();
 
 
-  // pluggable UI
-
-  const menuItems = React.useMemo(() => <>
-
-    <MenuItem onClick={toggleShowConversations}>
-      Conversations
-      <Switch checked={showConversations} sx={{ ml: 'auto' }} />
-    </MenuItem>
-
-    <MenuItem onClick={toggleShowSupport}>
-      Support
-      <Switch checked={showSupport} sx={{ ml: 'auto' }} />
-    </MenuItem>
-
-    <MenuItem onClick={toggleGrayUI}>
-      Grayed UI
-      <Switch checked={grayUI} sx={{ ml: 'auto' }} />
-    </MenuItem>
-
-  </>, [grayUI, showConversations, showSupport, toggleGrayUI, toggleShowConversations, toggleShowSupport]);
-
-  usePluggableOptimaLayout(null, null, menuItems, 'CallUI');
-
-
   return <>
 
+    {/* -> Panel */}
+    <OptimaPanelIn><ContactsMenuItems /></OptimaPanelIn>
+
     {/* Header "Call AGI" */}
     <Box sx={{
       my: 6,

src/apps/call/Telephone.tsx

@@ -1,5 +1,5 @@
 import * as React from 'react';
-import { shallow } from 'zustand/shallow';
+import { useShallow } from 'zustand/react/shallow';
 
 import { Box, Card, ListDivider, ListItemDecorator, MenuItem, Switch, Typography } from '@mui/joy';
 import ArrowBackIcon from '@mui/icons-material/ArrowBack';
@@ -11,19 +11,26 @@ import RecordVoiceOverTwoToneIcon from '@mui/icons-material/RecordVoiceOverTwoTo
 
 import { ScrollToBottom } from '~/common/scroll-to-bottom/ScrollToBottom';
 import { ScrollToBottomButton } from '~/common/scroll-to-bottom/ScrollToBottomButton';
-import { useChatLLMDropdown } from '../chat/components/useLLMDropdown';
+import { useChatLLMDropdown } from '../chat/components/layout-bar/useLLMDropdown';
 
-import { EXPERIMENTAL_speakTextStream } from '~/modules/elevenlabs/elevenlabs.client';
 import { SystemPurposeId, SystemPurposes } from '../../data';
-import { llmStreamingChatGenerate, VChatMessageIn } from '~/modules/llms/llm.client';
+import { elevenLabsSpeakText } from '~/modules/elevenlabs/elevenlabs.client';
+import { AixChatGenerateContent_DMessage, aixChatGenerateContent_DMessage_FromConversation } from '~/modules/aix/client/aix.client';
 import { useElevenLabsVoiceDropdown } from '~/modules/elevenlabs/useElevenLabsVoiceDropdown';
 
+import type { OptimaBarControlMethods } from '~/common/layout/optima/bar/OptimaBarDropdown';
+import { AudioPlayer } from '~/common/util/audio/AudioPlayer';
 import { Link } from '~/common/components/Link';
-import { SpeechResult, useSpeechRecognition } from '~/common/components/useSpeechRecognition';
-import { conversationTitle, createDMessage, DMessage, useChatStore } from '~/common/state/store-chats';
+import { OptimaPanelGroupedList } from '~/common/layout/optima/panel/OptimaPanelGroupedList';
+import { OptimaPanelIn, OptimaToolbarIn } from '~/common/layout/optima/portals/OptimaPortalsIn';
+import { SpeechResult, useSpeechRecognition } from '~/common/components/speechrecognition/useSpeechRecognition';
+import { conversationTitle, remapMessagesSysToUsr } from '~/common/stores/chat/chat.conversation';
+import { createDMessageFromFragments, createDMessageTextContent, DMessage, messageFragmentsReduceText, messageWasInterruptedAtStart } from '~/common/stores/chat/chat.message';
+import { createErrorContentFragment } from '~/common/stores/chat/chat.fragments';
 import { launchAppChat, navigateToIndex } from '~/common/app.routes';
-import { playSoundUrl, usePlaySoundUrl } from '~/common/util/audioUtils';
-import { usePluggableOptimaLayout } from '~/common/layout/optima/useOptimaLayout';
+import { useChatStore } from '~/common/stores/chat/store-chats';
+import { useGlobalShortcuts } from '~/common/components/shortcuts/useGlobalShortcuts';
+import { usePlayUrl } from '~/common/util/audio/usePlayUrl';
 
 import type { AppCallIntent } from './AppCall';
 import { CallAvatar } from './components/CallAvatar';
@@ -33,7 +40,7 @@ import { CallStatus } from './components/CallStatus';
 import { useAppCallStore } from './state/store-app-call';
 
 
-function CallMenuItems(props: {
+function CallMenu(props: {
   pushToTalk: boolean,
   setPushToTalk: (pushToTalk: boolean) => void,
   override: boolean,
@@ -48,7 +55,7 @@ function CallMenuItems(props: {
 
   const handleChangeVoiceToggle = () => props.setOverride(!props.override);
 
-  return <>
+  return <OptimaPanelGroupedList title='Call'>
 
     <MenuItem onClick={handlePushToTalkToggle}>
       <ListItemDecorator>{props.pushToTalk ? <MicNoneIcon /> : <MicIcon />}</ListItemDecorator>
@@ -78,7 +85,7 @@ function CallMenuItems(props: {
       Voice Calls Feedback
     </MenuItem>
 
-  </>;
+  </OptimaPanelGroupedList>;
 }
 
 
@@ -95,11 +102,12 @@ export function Telephone(props: {
   const [personaTextInterim, setPersonaTextInterim] = React.useState<string | null>(null);
   const [pushToTalk, setPushToTalk] = React.useState(true);
   const [stage, setStage] = React.useState<'ring' | 'declined' | 'connected' | 'ended'>('ring');
+  const llmDropdownRef = React.useRef<OptimaBarControlMethods>(null);
   const responseAbortController = React.useRef<AbortController | null>(null);
 
   // external state
-  const { chatLLMId, chatLLMDropdown } = useChatLLMDropdown();
-  const { chatTitle, reMessages } = useChatStore(state => {
+  const { chatLLMId: modelId, chatLLMDropdown: modelDropdown } = useChatLLMDropdown(llmDropdownRef);
+  const { chatTitle, reMessages } = useChatStore(useShallow(state => {
     const conversation = props.callIntent.conversationId
       ? state.conversations.find(conversation => conversation.id === props.callIntent.conversationId) ?? null
       : null;
@@ -107,7 +115,7 @@ export function Telephone(props: {
       chatTitle: conversation ? conversationTitle(conversation) : null,
       reMessages: conversation ? conversation.messages : null,
     };
-  }, shallow);
+  }));
   const persona = SystemPurposes[props.callIntent.personaId as SystemPurposeId] ?? undefined;
   const personaCallStarters = persona?.call?.starters ?? undefined;
   const personaVoiceId = overridePersonaVoice ? undefined : (persona?.voices?.elevenLabs?.voiceId ?? undefined);
@@ -118,12 +126,12 @@ export function Telephone(props: {
   const onSpeechResultCallback = React.useCallback((result: SpeechResult) => {
     setSpeechInterim(result.done ? null : { ...result });
     if (result.done) {
-      const transcribed = result.transcript.trim();
-      if (transcribed.length >= 1)
-        setCallMessages(messages => [...messages, createDMessage('user', transcribed)]);
+      const userSpeechTranscribed = result.transcript.trim();
+      if (userSpeechTranscribed.length >= 1)
+        setCallMessages(messages => [...messages, createDMessageTextContent('user', userSpeechTranscribed)]); // [state] append user:speech
     }
   }, []);
-  const { isSpeechEnabled, isRecording, isRecordingAudio, isRecordingSpeech, startRecording, stopRecording, toggleRecording } = useSpeechRecognition(onSpeechResultCallback, 1000);
+  const { recognitionState, startRecognition, stopRecognition, toggleRecognition } = useSpeechRecognition('webSpeechApi', onSpeechResultCallback, 1000);
 
   // derived state
   const isRinging = stage === 'ring';
@@ -136,17 +144,23 @@ export function Telephone(props: {
 
   // pickup / hangup
   React.useEffect(() => {
-    !isRinging && playSoundUrl(isConnected ? '/sounds/chat-begin.mp3' : '/sounds/chat-end.mp3');
+    !isRinging && AudioPlayer.playUrl(isConnected ? '/sounds/chat-begin.mp3' : '/sounds/chat-end.mp3');
   }, [isRinging, isConnected]);
 
   // ringtone
-  usePlaySoundUrl(isRinging ? '/sounds/chat-ringtone.mp3' : null, 300, 2800 * 2);
+  usePlayUrl(isRinging ? '/sounds/chat-ringtone.mp3' : null, 300, 2800 * 2);
 
 
+  /// Shortcuts
+
+  useGlobalShortcuts('Telephone', React.useMemo(() => [
+    { key: 'm', ctrl: true, action: toggleRecognition },
+  ], [toggleRecognition]));
+
   /// CONNECTED
 
   const handleCallStop = () => {
-    stopRecording();
+    stopRecognition(false);
     setStage('ended');
   };
 
@@ -169,9 +183,10 @@ export function Telephone(props: {
     const phoneMessages = personaCallStarters || ['Hello?', 'Hey!'];
     const firstMessage = phoneMessages[Math.floor(Math.random() * phoneMessages.length)];
 
-    setCallMessages([createDMessage('assistant', firstMessage)]);
+    setCallMessages([createDMessageTextContent('assistant', firstMessage)]); // [state] set assistant:hello message
+
     // fire/forget
-    void EXPERIMENTAL_speakTextStream(firstMessage, personaVoiceId);
+    void elevenLabsSpeakText(firstMessage, personaVoiceId, true, true);
 
     return () => clearInterval(interval);
   }, [isConnected, personaCallStarters, personaVoiceId]);
@@ -179,22 +194,30 @@ export function Telephone(props: {
   // [E] persona streaming response - upon new user message
   React.useEffect(() => {
     // only act when we have a new user message
-    if (!isConnected || callMessages.length < 1 || callMessages[callMessages.length - 1].role !== 'user')
+    if (!isConnected || callMessages.length < 1)
       return;
-    switch (callMessages[callMessages.length - 1].text) {
+
+    // Voice commands
+    const lastUserMessage = callMessages[callMessages.length - 1];
+    if (lastUserMessage.role !== 'user')
+      return;
+    switch (messageFragmentsReduceText(lastUserMessage.fragments)) {
       // do not respond
       case 'Stop.':
         return;
+
       // command: close the call
       case 'Goodbye.':
         setStage('ended');
         setTimeout(launchAppChat, 2000);
         return;
+
       // command: regenerate answer
       case 'Retry.':
       case 'Try again.':
         setCallMessages(messages => messages.slice(0, messages.length - 2));
         return;
+
       // command: restart chat
       case 'Restart.':
         setCallMessages([]);
@@ -202,55 +225,73 @@ export function Telephone(props: {
     }
 
     // bail if no llm selected
-    if (!chatLLMId) return;
+    if (!modelId) return;
 
-    // temp fix: when the chat has no messages, only assume a single system message
-    const chatMessages: { role: VChatMessageIn['role'], text: string }[] = (reMessages && reMessages.length > 0)
-      ? reMessages
-      : personaSystemMessage
-        ? [{ role: 'system', text: personaSystemMessage }]
-        : [];
 
-    // 'prompt' for a "telephone call"
-    // FIXME: can easily run ouf of tokens - if this gets traction, we'll fix it
-    const callPrompt: VChatMessageIn[] = [
-      { role: 'system', content: 'You are having a phone call. Your response style is brief and to the point, and according to your personality, defined below.' },
-      ...chatMessages.map(message => ({ role: message.role, content: message.text })),
-      { role: 'system', content: 'You are now on the phone call related to the chat above. Respect your personality and answer with short, friendly and accurate thoughtful lines.' },
-      ...callMessages.map(message => ({ role: message.role, content: message.text })),
+    // Call Message Generation Prompt
+    const callSystemInstruction = createDMessageTextContent('system', 'You are having a phone call. Your response style is brief and to the point, and according to your personality, defined below.');
+    const reMessagesRemapSysToUsr = remapMessagesSysToUsr(reMessages);
+    const callGenerationInputHistory: DMessage[] = [
+      // Chat messages, including the system prompt which is casted to a user message
+      // TODO: when upgrading to dynamic personas, we need to inject the persona message instead - not rely on reMessages, as messages[0] !== 'system'
+      ...(reMessagesRemapSysToUsr ? reMessagesRemapSysToUsr : [createDMessageTextContent('user', personaSystemMessage)]),
+      // Call system prompt 2, to indicate the call has started
+      createDMessageTextContent('user', '**You are now on the phone call related to the chat above**.\nRespect your personality and answer with short, friendly and accurate thoughtful brief lines.'),
+      // Call history
+      ...callMessages,
     ];
 
+
     // perform completion
     responseAbortController.current = new AbortController();
     let finalText = '';
-    let error: any | null = null;
     setPersonaTextInterim('💭...');
-    llmStreamingChatGenerate(chatLLMId, callPrompt, null, null, responseAbortController.current.signal, ({ textSoFar }) => {
-      const text = textSoFar?.trim();
-      if (text) {
-        finalText = text;
-        setPersonaTextInterim(text);
-      }
+
+    aixChatGenerateContent_DMessage_FromConversation(
+      modelId,
+      callSystemInstruction,
+      callGenerationInputHistory,
+      'call',
+      callMessages[0].id,
+      { abortSignal: responseAbortController.current.signal },
+      (update: AixChatGenerateContent_DMessage, _isDone: boolean) => {
+        const updatedText = messageFragmentsReduceText(update.fragments).trim();
+        if (updatedText)
+          setPersonaTextInterim(finalText = updatedText);
+      },
+    ).then((status) => {
+
+      // don't add the message to conversation if it was interrupted with no content
+      if (messageWasInterruptedAtStart(status.lastDMessage))
+        return;
+
+      // whether status.outcome === 'success' or not, we get a valid DMessage, eventually with Error Fragments inside
+      const fullMessage = createDMessageFromFragments('assistant', status.lastDMessage.fragments);
+      fullMessage.generator = status.lastDMessage.generator;
+      setCallMessages(messages => [...messages, fullMessage]); // [state] append assistant:call_response
+
+      // fire/forget
+      if (status.outcome === 'success' && finalText?.length >= 1)
+        void elevenLabsSpeakText(finalText, personaVoiceId, true, true);
+
     }).catch((err: DOMException) => {
-      if (err?.name !== 'AbortError')
-        error = err;
+      if (err?.name !== 'AbortError') {
+        // create an error message to explain the exception
+        const errorMessage = createDMessageFromFragments('assistant', [createErrorContentFragment(err.message || err.toString())]);
+        setCallMessages(messages => [...messages, errorMessage]); // [state] append assistant:call_response-ERROR
+      }
     }).finally(() => {
       setPersonaTextInterim(null);
-      if (finalText || error)
-        setCallMessages(messages => [...messages, createDMessage('assistant', finalText + (error ? ` (ERROR: ${error.message || error.toString()})` : ''))]);
-      // fire/forget
-      if (finalText?.length >= 1)
-        void EXPERIMENTAL_speakTextStream(finalText, personaVoiceId);
     });
 
     return () => {
       responseAbortController.current?.abort();
       responseAbortController.current = null;
     };
-  }, [isConnected, callMessages, chatLLMId, personaVoiceId, personaSystemMessage, reMessages]);
+  }, [isConnected, callMessages, modelId, personaVoiceId, personaSystemMessage, reMessages]);
 
   // [E] Message interrupter
-  const abortTrigger = isConnected && isRecordingSpeech;
+  const abortTrigger = isConnected && recognitionState.hasSpeech;
   React.useEffect(() => {
     if (abortTrigger && responseAbortController.current) {
       responseAbortController.current.abort();
@@ -261,34 +302,33 @@ export function Telephone(props: {
 
 
   // [E] continuous speech recognition (reload)
-  const shouldStartRecording = isConnected && !pushToTalk && speechInterim === null && !isRecordingAudio;
+  const shouldStartRecording = isConnected && !pushToTalk && speechInterim === null && !recognitionState.hasAudio;
   React.useEffect(() => {
     if (shouldStartRecording)
-      startRecording();
-  }, [shouldStartRecording, startRecording]);
+      startRecognition();
+  }, [shouldStartRecording, startRecognition]);
 
 
   // more derived state
   const personaName = persona?.title ?? 'Unknown';
-  const isMicEnabled = isSpeechEnabled;
+  const isMicEnabled = recognitionState.isAvailable;
   const isTTSEnabled = true;
   const isEnabled = isMicEnabled && isTTSEnabled;
-
-
-  // pluggable UI
-
-  const menuItems = React.useMemo(() =>
-      <CallMenuItems
-        pushToTalk={pushToTalk} setPushToTalk={setPushToTalk}
-        override={overridePersonaVoice} setOverride={setOverridePersonaVoice} />
-    , [overridePersonaVoice, pushToTalk],
-  );
-
-  usePluggableOptimaLayout(null, chatLLMDropdown, menuItems, 'CallUI');
+  const micErrorMessage = recognitionState.errorMessage;
 
 
   return <>
 
+    {/* -> Toolbar */}
+    <OptimaToolbarIn>{modelDropdown}</OptimaToolbarIn>
+    {/* -> Panel */}
+    <OptimaPanelIn>
+      <CallMenu
+        pushToTalk={pushToTalk} setPushToTalk={setPushToTalk}
+        override={overridePersonaVoice} setOverride={setOverridePersonaVoice}
+      />
+    </OptimaPanelIn>
+
     <Typography
       level='h1'
       sx={{
@@ -311,7 +351,7 @@ export function Telephone(props: {
       callerName={isConnected ? undefined : personaName}
       statusText={isRinging ? '' /*'is calling you'*/ : isDeclined ? 'call declined' : isEnded ? 'call ended' : callElapsedTime}
       regardingText={chatTitle}
-      micError={!isMicEnabled} speakError={!isTTSEnabled}
+      micError={!isMicEnabled} micErrorMessage={micErrorMessage} speakError={!isTTSEnabled}
     />
 
     {/* Live Transcript, w/ streaming messages, audio indication, etc. */}
@@ -339,7 +379,7 @@ export function Telephone(props: {
             {callMessages.map((message) =>
               <CallMessage
                 key={message.id}
-                text={message.text}
+                text={messageFragmentsReduceText(message.fragments)}
                 variant={message.role === 'assistant' ? 'solid' : 'soft'}
                 color={message.role === 'assistant' ? 'neutral' : 'primary'}
                 role={message.role}
@@ -357,10 +397,10 @@ export function Telephone(props: {
             )}
 
             {/* Listening... */}
-            {isRecording && (
+            {recognitionState.isActive && (
               <CallMessage
                 text={<>{speechInterim?.transcript.trim() || null}{speechInterim?.interimTranscript.trim() ? <i> {speechInterim.interimTranscript}</i> : null}</>}
-                variant={(isRecordingSpeech || !!speechInterim?.transcript) ? 'soft' : 'outlined'}
+                variant={(recognitionState.hasSpeech || !!speechInterim?.transcript) ? 'soft' : 'outlined'}
                 color='primary'
                 role='user'
               />
@@ -386,11 +426,11 @@ export function Telephone(props: {
       {isConnected && <CallButton Icon={CallEndIcon} text='Hang up' color='danger' variant='soft' onClick={handleCallStop} />}
       {isConnected && (pushToTalk ? (
           <CallButton
-            Icon={MicIcon} onClick={toggleRecording}
-            text={isRecordingSpeech ? 'Listening...' : isRecording ? 'Listening' : 'Push To Talk'}
-            variant={isRecordingSpeech ? 'solid' : isRecording ? 'soft' : 'outlined'}
+            Icon={MicIcon} onClick={toggleRecognition}
+            text={recognitionState.hasSpeech ? 'Listening...' : recognitionState.isActive ? 'Listening' : 'Push To Talk'}
+            variant={recognitionState.hasSpeech ? 'solid' : recognitionState.isActive ? 'soft' : 'outlined'}
             color='primary'
-            sx={!isRecording ? { backgroundColor: 'background.surface' } : undefined}
+            sx={!recognitionState.isActive ? { backgroundColor: 'background.surface' } : undefined}
           />
         ) : null
         // <CallButton disabled={true} Icon={MicOffIcon} onClick={() => setMicMuted(muted => !muted)}
@@ -406,9 +446,9 @@ export function Telephone(props: {
 
     {/* DEBUG state */}
     {avatarClickCount > 10 && (avatarClickCount % 2 === 0) && (
-      <Card variant='outlined' sx={{ maxHeight: '25dvh', overflow: 'auto', whiteSpace: 'pre', py: 0, width: '100%' }}>
-        Special commands: Stop, Retry, Try Again, Restart, Goodbye.
-        {JSON.stringify({ isSpeechEnabled, isRecordingAudio, speechInterim }, null, 2)}
+      <Card variant='outlined' sx={{ maxHeight: '25dvh', fontSize: 'sm', overflow: 'auto', whiteSpace: 'pre', py: 0, width: '100%' }}>
+        Special commands: Stop, Retry, Try Again, Restart, Goodbye.<br />
+        {JSON.stringify({ ...recognitionState, speechInterim }, null, 2)}
       </Card>
     )}
 

src/apps/call/components/CallMessage.tsx

@@ -3,13 +3,13 @@ import * as React from 'react';
 import { Chip, ColorPaletteProp, VariantProp } from '@mui/joy';
 import { SxProps } from '@mui/joy/styles/types';
 
-import type { VChatMessageIn } from '~/modules/llms/llm.client';
+import type { DMessage } from '~/common/stores/chat/chat.message';
 
 
 export function CallMessage(props: {
   text?: string | React.JSX.Element,
   variant?: VariantProp, color?: ColorPaletteProp,
-  role: VChatMessageIn['role'],
+  role: DMessage['role'],
   sx?: SxProps,
 }) {
   const isUserMessage = props.role === 'user';