feat: add agent program management backend

* feat: add role aware agent creation

* feat: support custom role aware agents

* feat: add plain agent creation mode

* fix: validate custom role arrays

.claude/skills/write-docs/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: write-docs
+description: Write BrowserOS feature documentation. Use when the user wants to create or update documentation for a BrowserOS feature. This skill explores the codebase to understand features and writes concise Mintlify MDX docs.
+allowed-tools: Read, Grep, Glob, Bash, Task, Write, Edit
+---
+
+# Write BrowserOS Documentation
+
+This skill helps write documentation for BrowserOS features. It follows a structured workflow to create high-quality, concise documentation pages.
+
+## Workflow
+
+### Step 1: Understand the Feature
+
+Before writing documentation, explore the codebase to understand the feature:
+
+1. **Ask the user** which feature they want to document
+2. **Search the codebase** at `../browseros-server` (sibling directory) to find relevant code:
+   - Use `Grep` to search for feature-related keywords
+   - Use `Glob` to find relevant files
+   - Read key files to understand how the feature works
+3. **Identify key aspects**:
+   - What problem does this feature solve?
+   - How does the user enable/configure it?
+   - What are the main use cases?
+
+### Step 2: Gather Screenshots
+
+Ask the user to provide screenshots for the documentation:
+
+1. Tell the user: "Please copy a screenshot to your clipboard (Cmd+C) that shows [specific UI element]"
+2. Run: `python scripts/save_clipboard.py docs/images/<feature-name>.png`
+3. Repeat for any additional screenshots needed
+
+### Step 3: Write the Documentation
+
+Create the MDX file at `docs/features/<feature-name>.mdx` (or appropriate location) following this structure:
+
+```mdx
+---
+title: "Feature Name"
+description: "One sentence describing what this feature does"
+---
+
+[Opening paragraph: 1-2 sentences explaining what the feature does and why it matters]
+
+## How It Works
+
+[Explain the core mechanics in 2-3 paragraphs max]
+
+## Getting Started
+
+[Step-by-step instructions to use the feature]
+
+1. Step one
+2. Step two
+3. Step three
+
+## [Optional: Additional Sections]
+
+[Only if necessary - keep the doc to ONE PAGE maximum]
+```
+
+### Step 4: Update Navigation
+
+Add the new page to `docs/docs.json` under the appropriate group in the `navigation.groups` array.
+
+### Step 5: Preview
+
+Tell the user to run `mint dev` in the `docs/` directory to preview the documentation.
+
+## Documentation Style Guide
+
+- **Concise**: Maximum one page length
+- **Clear**: Write for first-time BrowserOS users
+- **Practical**: Focus on how to use the feature, not internal implementation details
+- **Visual**: Use screenshots to show, not just tell
+- **No fluff**: Skip unnecessary introductions or conclusions
+
+## Example: Ad Blocking Doc Structure
+
+```mdx
+---
+title: "Ad Blocking"
+description: "BrowserOS blocks 10x more ads than Chrome out of the box"
+---
+
+BrowserOS ships with built-in ad blocking that works immediately—no extensions required.
+
+## How It Works
+
+[2-3 paragraphs explaining the mechanics]
+
+## BrowserOS vs Chrome
+
+[Comparison with data/screenshots]
+
+## What This Means
+
+[1 paragraph on the practical benefits]
+```
+
+## Key Directories
+
+- **Docs location**: `docs/`
+- **Images**: `docs/images/`
+- **Feature code**: `../browseros-server/` (sibling directory)
+- **Config**: `docs/docs.json`
+
+## Core Features to Document
+
+The user mentioned these features need documentation:
+1. BrowserOS MCP Server
+2. Connecting other MCPs to BrowserOS assistant
+3. Scheduled tasks
+4. [Additional features discovered in codebase]

.config/README.md

@@ -0,0 +1,34 @@
+# Worktrunk Setup
+
+This repo uses [Worktrunk](https://github.com/max-sixty/worktrunk) for running multiple Claude Code agents in parallel on different branches.
+
+## Install Worktrunk
+
+```bash
+brew install max-sixty/worktrunk/wt
+wt config shell install
+# restart terminal
+```
+
+## Quick Commands
+
+| Task | Command |
+|------|---------|
+| Create worktree + start Claude | `wt switch -c -x claude feat-name` |
+| Switch to existing worktree | `wt switch feat-name` |
+| List all worktrees | `wt list` |
+| Create PR | `gh pr create` |
+| Remove worktree | `wt remove feat-name` |
+
+## What happens on `wt switch -c`
+
+1. Creates new worktree at `../browseros-main.feat-name/`
+2. Runs `bun install` in `packages/browseros-agent/`
+3. Copies `.env.*` files from main worktree's `packages/browseros-agent/apps/`
+
+## Hooks
+
+Hooks are configured in `.config/wt.toml`:
+
+- **post-create**: Runs `bun install` in the agent package, copies env files and `.llm/` from the main worktree
+- **pre-remove**: Syncs `.llm/` back to the main worktree before deletion

.config/wt.toml

@@ -1,4 +1,6 @@
 [post-create]
+install = "cd packages/browseros-agent && bun install"
+env = "for f in {{ repo_root }}/packages/browseros-agent/apps/*/.env.*; do [ -f \"$f\" ] && cp \"$f\" \"${f#{{ repo_root }}/}\"; done 2>/dev/null || true"
 llm = "cp -r {{ repo_root }}/.llm . 2>/dev/null || true"
 
 [pre-remove]

.gitattributes

@@ -3,5 +3,12 @@ resources/nxtscape-productivity.gif filter=lfs diff=lfs merge=lfs -text
 resources/media/nxtscape-agent.gif filter=lfs diff=lfs merge=lfs -text
 resources/media/nxtscape-chat.gif filter=lfs diff=lfs merge=lfs -text
 docs/videos/browserOS-agent-in-action.gif filter=lfs diff=lfs merge=lfs -text
-docs/images/** filter=lfs diff=lfs merge=lfs -text
+# Mark Python build/tooling files as generated so they don't count in language stats
+packages/browseros/build/**/*.py linguist-generated
+packages/browseros/chromium_patches/**/*.py linguist-generated
+scripts/*.py linguist-generated
+# Mark build directories as generated
+build/* linguist-generated
+# Mark eval/test framework as vendored so it's excluded from language stats
+packages/browseros-agent/apps/eval/** linguist-vendored
 docs/videos/** filter=lfs diff=lfs merge=lfs -text

.github/workflows/audit.yml

@@ -0,0 +1,192 @@
+name: Daily Security Audit
+
+on:
+  schedule:
+    # Runs at midnight IST (6:30 PM UTC previous day)
+    - cron: "30 18 * * *"
+  workflow_dispatch: # Allows manual triggering
+
+jobs:
+  security-audit:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: packages/browseros-agent
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v6
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+
+      - name: Install dependencies
+        run: bun ci
+
+      - name: Run security audit
+        id: audit
+        continue-on-error: true
+        run: |
+          # Run audit and capture output (skip the version line)
+          bun audit --json 2>&1 | tail -n 1 > audit-results.json || true
+
+          # Check if vulnerabilities exist
+          VULN_COUNT=$(cat audit-results.json | bun -e "const data = JSON.parse(require('fs').readFileSync(0, 'utf-8')); console.log(Object.keys(data).reduce((sum, pkg) => sum + data[pkg].length, 0))")
+          echo "vuln_count=$VULN_COUNT" >> $GITHUB_OUTPUT
+
+      - name: Parse audit results
+        id: parse
+        if: always()
+        run: |
+          cat > parse-audit.ts << 'EOF'
+          const fs = require('fs');
+          const auditData = JSON.parse(fs.readFileSync('audit-results.json', 'utf-8'));
+
+          // Collect all vulnerabilities from all packages
+          const allVulns: any[] = [];
+          let totalCount = 0;
+
+          for (const [packageName, vulns] of Object.entries(auditData)) {
+            if (Array.isArray(vulns)) {
+              vulns.forEach((vuln: any) => {
+                allVulns.push({ ...vuln, packageName });
+                totalCount++;
+              });
+            }
+          }
+
+          if (totalCount === 0) {
+            console.log(JSON.stringify({
+              text: "✅ *Daily Security Audit - No Vulnerabilities Found*",
+              blocks: [
+                {
+                  type: "section",
+                  text: {
+                    type: "mrkdwn",
+                    text: "✅ *Daily Security Audit*\n\nNo vulnerabilities found in dependencies!"
+                  }
+                },
+                {
+                  type: "context",
+                  elements: [
+                    {
+                      type: "mrkdwn",
+                      text: `Repository: ${process.env.GITHUB_REPOSITORY} | Branch: ${process.env.GITHUB_REF_NAME}`
+                    }
+                  ]
+                }
+              ]
+            }));
+            process.exit(0);
+          }
+
+          // Count by severity
+          const severityCounts = {
+            critical: 0,
+            high: 0,
+            moderate: 0,
+            low: 0
+          };
+
+          allVulns.forEach(vuln => {
+            severityCounts[vuln.severity as keyof typeof severityCounts]++;
+          });
+
+          let message = `⚠️ *Daily Security Audit - ${totalCount} Vulnerabilit${totalCount === 1 ? 'y' : 'ies'} Found*\n\n`;
+          message += `*Severity Breakdown:*\n`;
+          message += `• Critical: ${severityCounts.critical}\n`;
+          message += `• High: ${severityCounts.high}\n`;
+          message += `• Moderate: ${severityCounts.moderate}\n`;
+          message += `• Low: ${severityCounts.low}\n\n`;
+
+          message += `*Top Vulnerabilities:*\n`;
+
+          // Sort by severity
+          const severityOrder = { critical: 0, high: 1, moderate: 2, low: 3 };
+          allVulns.sort((a, b) =>
+            severityOrder[a.severity as keyof typeof severityOrder] -
+            severityOrder[b.severity as keyof typeof severityOrder]
+          );
+
+          allVulns.slice(0, 5).forEach(vuln => {
+            const emoji = {
+              critical: '🔴',
+              high: '🟠',
+              moderate: '🟡',
+              low: '🟢'
+            }[vuln.severity] || '⚪';
+
+            message += `\n${emoji} *${vuln.title}*\n`;
+            message += `   Package: \`${vuln.packageName}\`\n`;
+            message += `   Severity: ${vuln.severity.toUpperCase()}\n`;
+            message += `   Vulnerable: ${vuln.vulnerable_versions}\n`;
+            if (vuln.cwe?.length) {
+              message += `   CWE: ${vuln.cwe.join(', ')}\n`;
+            }
+            if (vuln.cvss?.score) {
+              message += `   CVSS: ${vuln.cvss.score}\n`;
+            }
+            if (vuln.url) {
+              message += `   <${vuln.url}|View Details>\n`;
+            }
+          });
+
+          if (allVulns.length > 5) {
+            message += `\n_...and ${allVulns.length - 5} more vulnerabilit${allVulns.length - 5 === 1 ? 'y' : 'ies'}_`;
+          }
+
+          const payload = {
+            text: `⚠️ Security Audit: ${totalCount} vulnerabilit${totalCount === 1 ? 'y' : 'ies'} found`,
+            blocks: [
+              {
+                type: "section",
+                text: {
+                  type: "mrkdwn",
+                  text: message
+                }
+              },
+              {
+                type: "actions",
+                elements: [
+                  {
+                    type: "button",
+                    text: {
+                      type: "plain_text",
+                      text: "View Full Report"
+                    },
+                    url: `https://github.com/${process.env.GITHUB_REPOSITORY}/actions/runs/${process.env.GITHUB_RUN_ID}`
+                  }
+                ]
+              },
+              {
+                type: "context",
+                elements: [
+                  {
+                    type: "mrkdwn",
+                    text: `Repository: ${process.env.GITHUB_REPOSITORY} | Branch: ${process.env.GITHUB_REF_NAME}`
+                  }
+                ]
+              }
+            ]
+          };
+
+          console.log(JSON.stringify(payload));
+          EOF
+
+          bun run parse-audit.ts > slack-payload.json
+
+      - name: Send to Slack
+        if: always()
+        env:
+          SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }}
+        run: |
+          curl -X POST \
+            -H 'Content-Type: application/json' \
+            -d @slack-payload.json \
+            $SLACK_WEBHOOK_URL
+
+      - name: Fail if vulnerabilities found
+        if: steps.audit.outputs.vuln_count != '0'
+        run: |
+          echo "Security audit found vulnerabilities"
+          exit 1

.github/workflows/branch-cleaner.yml

@@ -0,0 +1,17 @@
+name: GitHub Branch Cleaner
+
+on:
+  schedule:
+    - cron: '0 0 * * 0'
+  workflow_dispatch:
+
+jobs:
+  cleanup:
+    name: Clean up merged branches
+    runs-on: ubuntu-latest
+    steps:
+      - uses: mmorenoregalado/action-branches-cleaner@v2.0.3
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          base_branches: main
+          days_old_threshold: 30

.github/workflows/cla.yml

@@ -1,11 +1,11 @@
-name: 'CLA Assistant'
+name: CLA Assistant
+
 on:
   issue_comment:
     types: [created]
   pull_request_target:
     types: [opened, closed, synchronize]
 
-# Explicitly configure permissions
 permissions:
   actions: write
   contents: write
@@ -13,47 +13,46 @@ permissions:
   statuses: write
 
 jobs:
-  CLAAssistant:
+  cla:
     runs-on: ubuntu-latest
+    if: |
+      (github.event_name == 'pull_request_target') ||
+      (github.event_name == 'issue_comment' && github.event.issue.pull_request &&
+       (github.event.comment.body == 'recheck' ||
+        github.event.comment.body == 'I have read the CLA Document and I hereby sign the CLA'))
     steps:
-      - name: 'CLA Assistant'
-        if: (github.event.comment.body == 'recheck' || github.event.comment.body == 'I have read the CLA Document and I hereby sign the CLA') || github.event_name == 'pull_request_target'
+      - name: CLA Assistant
         uses: contributor-assistant/github-action@v2.6.1
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          PERSONAL_ACCESS_TOKEN: ${{ secrets.CLA_SIGNATURES_TOKEN }}
         with:
-          # Path where signatures will be stored
-          path-to-signatures: 'signatures/version1/cla.json'
-
-          # Path to your CLA document
-          path-to-document: 'https://github.com/browseros-ai/BrowserOS/blob/main/CLA.md'
-
-          # Branch to store signatures (should not be protected)
+          path-to-signatures: 'cla-signatures.json'
+          path-to-document: 'https://github.com/${{ github.repository }}/blob/main/CLA.md'
           branch: 'main'
-
-          # Allowlist for users who don't need to sign (bots, core team members)
-          allowlist: shadowfax92,felarof99,dependabot[bot],renovate[bot],github-actions[bot]
-
-          # Optional: Custom messages
+          remote-organization-name: 'browseros-ai'
+          remote-repository-name: 'cla-signatures'
+          allowlist: 'shadowfax92,felarof99,bot*,*[bot],dependabot,renovate,github-actions,snyk-bot,imgbot,greenkeeper,semantic-release-bot,allcontributors'
+          lock-pullrequest-aftermerge: false
           custom-notsigned-prcomment: |
-            **CLA Assistant Lite bot** Thank you for your submission! We require contributors to sign our [Contributor License Agreement](https://github.com/browseros-ai/BrowserOS/blob/main/CLA.md) before we can accept your contribution.
+            Thank you for your contribution! Before we can merge this PR, we need you to sign our [Contributor License Agreement](https://github.com/${{ github.repository }}/blob/main/CLA.md).
 
-            By signing the CLA, you confirm that:
-            - You have read and agree to the AGPL-3.0 license terms
-            - Your contribution is your original work
-            - You grant us the rights to use your contribution under the AGPL-3.0 license
+            **To sign the CLA**, please add a comment to this PR with the following text:
 
-            **To sign the CLA, please comment on this PR with:**
-            `I have read the CLA Document and I hereby sign the CLA`
+            ```
+            I have read the CLA Document and I hereby sign the CLA
+            ```
 
+            You only need to sign once. After signing, this check will pass automatically.
+
+            ---
+            <details>
+            <summary>Troubleshooting</summary>
+
+            - **Already signed but still failing?** Comment `recheck` to trigger a re-verification.
+            - **Signed with a different email?** Make sure your commit email matches your GitHub account email, or add your commit email to your GitHub account.
+
+            </details>
           custom-pr-sign-comment: 'I have read the CLA Document and I hereby sign the CLA'
-
           custom-allsigned-prcomment: |
-            **CLA Assistant Lite bot** ✅ All contributors have signed the CLA. Thank you for helping make BrowserOS better!
-
-          # Lock PR after merge to prevent signature tampering
-          lock-pullrequest-aftermerge: true
-
-          # Custom commit messages
-          create-file-commit-message: 'docs: Create CLA signatures file'
-          signed-commit-message: 'docs: $contributorName signed the CLA in $owner/$repo#$pullRequestNo'
+            All contributors have signed the CLA. Thank you!

.github/workflows/claude.yml

@@ -0,0 +1,42 @@
+name: Claude Code
+
+on:
+  pull_request:
+    types: [opened, ready_for_review]
+  issue_comment:
+    types: [created]
+  pull_request_review_comment:
+    types: [created]
+  issues:
+    types: [opened, assigned]
+  pull_request_review:
+    types: [submitted]
+
+jobs:
+  claude:
+    if: |
+      github.event_name == 'pull_request' ||
+      (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude') && contains(fromJSON('["OWNER","MEMBER","COLLABORATOR"]'), github.event.comment.author_association)) ||
+      (github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude') && contains(fromJSON('["OWNER","MEMBER","COLLABORATOR"]'), github.event.comment.author_association)) ||
+      (github.event_name == 'pull_request_review' && contains(github.event.review.body, '@claude') && contains(fromJSON('["OWNER","MEMBER","COLLABORATOR"]'), github.event.review.author_association)) ||
+      (github.event_name == 'issues' && (contains(github.event.issue.body, '@claude') || contains(github.event.issue.title, '@claude')))
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+      issues: read
+      id-token: write
+      actions: read
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 1
+
+      - name: Run Claude Code
+        id: claude
+        uses: anthropics/claude-code-action@v1
+        with:
+          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+          additional_permissions: |
+            actions: read

.github/workflows/code-quality.yml

@@ -0,0 +1,61 @@
+name: Code Quality
+
+on:
+  pull_request:
+    branches:
+      - main
+      - dev
+    paths:
+      - "packages/browseros-agent/**"
+
+jobs:
+  biome:
+    name: runner / Biome
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: packages/browseros-agent
+    permissions:
+      contents: read
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+
+      - name: Setup Biome
+        uses: biomejs/setup-biome@v2
+        with:
+          version: latest
+
+      - name: Run Biome
+        run: biome ci .
+
+  typecheck:
+    name: runner / Typecheck
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: packages/browseros-agent
+    permissions:
+      contents: read
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+
+      - name: Install dependencies
+        run: bun ci
+
+      - name: Prepare wxt
+        run: VITE_PUBLIC_BROWSEROS_API=http://localhost:3000 bun run --cwd apps/agent wxt prepare
+
+      - name: Run codegen
+        run: bun run --cwd apps/agent codegen
+
+      - name: Run Typecheck
+        run: bun run typecheck

.github/workflows/eval-weekly.yml

@@ -0,0 +1,98 @@
+name: Weekly Eval
+
+on:
+  schedule:
+    # Every Saturday at 06:00 UTC
+    - cron: '0 6 * * 6'
+  push:
+    branches: [main]
+    paths:
+      - 'packages/browseros-agent/apps/server/src/agent/**'
+      - 'packages/browseros-agent/apps/server/src/tools/**'
+  workflow_dispatch:
+    inputs:
+      config:
+        description: 'Eval config file (relative to apps/eval/)'
+        required: false
+        default: 'configs/browseros-agent-weekly.json'
+
+permissions:
+  contents: read
+
+jobs:
+  eval:
+    runs-on: ubuntu-latest
+    timeout-minutes: 360
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install BrowserOS
+        run: |
+          wget -q https://github.com/browseros-ai/BrowserOS/releases/download/v0.44.0.1/BrowserOS_v0.44.0.1_amd64.deb
+          sudo dpkg -i BrowserOS_v0.44.0.1_amd64.deb
+          browseros --version || echo "BrowserOS installed at $(which browseros)"
+
+      - name: Install Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - name: Install dependencies
+        working-directory: packages/browseros-agent
+        run: bun install --ignore-scripts && bun run build:agent-sdk
+
+      - name: Install xvfb
+        run: sudo apt-get update && sudo apt-get install -y xvfb
+
+      - name: Install captcha solver extension
+        working-directory: packages/browseros-agent/apps/eval
+        run: |
+          mkdir -p extensions
+          curl -sL -o /tmp/nopecha.zip https://github.com/NopeCHALLC/nopecha-extension/releases/latest/download/chromium_automation.zip
+          unzip -qo /tmp/nopecha.zip -d extensions/nopecha
+
+      - name: Run eval
+        working-directory: packages/browseros-agent/apps/eval
+        env:
+          FIREWORKS_API_KEY: ${{ secrets.FIREWORKS_API_KEY }}
+          CLAUDE_CODE_OAUTH_TOKEN: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+          NOPECHA_API_KEY: ${{ secrets.NOPECHA_API_KEY }}
+          BROWSEROS_BINARY: /usr/bin/browseros
+          EVAL_CONFIG: ${{ github.event.inputs.config || 'configs/browseros-agent-weekly.json' }}
+        run: |
+          echo "Running eval with config: $EVAL_CONFIG"
+          xvfb-run --auto-servernum --server-args="-screen 0 1440x900x24" bun run src/index.ts -c "$EVAL_CONFIG"
+
+      - name: Upload runs to R2
+        if: success()
+        working-directory: packages/browseros-agent/apps/eval
+        env:
+          EVAL_R2_ACCOUNT_ID: ${{ secrets.EVAL_R2_ACCOUNT_ID }}
+          EVAL_R2_ACCESS_KEY_ID: ${{ secrets.EVAL_R2_ACCESS_KEY_ID }}
+          EVAL_R2_SECRET_ACCESS_KEY: ${{ secrets.EVAL_R2_SECRET_ACCESS_KEY }}
+          EVAL_R2_BUCKET: ${{ secrets.EVAL_R2_BUCKET }}
+          EVAL_R2_CDN_BASE_URL: ${{ secrets.EVAL_R2_CDN_BASE_URL }}
+          EVAL_CONFIG: ${{ github.event.inputs.config || 'configs/browseros-agent-weekly.json' }}
+        run: |
+          CONFIG_NAME=$(basename "$EVAL_CONFIG" .json)
+          bun scripts/upload-run.ts "results/$CONFIG_NAME"
+
+      - name: Generate trend report
+        if: success()
+        working-directory: packages/browseros-agent
+        env:
+          EVAL_R2_ACCOUNT_ID: ${{ secrets.EVAL_R2_ACCOUNT_ID }}
+          EVAL_R2_ACCESS_KEY_ID: ${{ secrets.EVAL_R2_ACCESS_KEY_ID }}
+          EVAL_R2_SECRET_ACCESS_KEY: ${{ secrets.EVAL_R2_SECRET_ACCESS_KEY }}
+          EVAL_R2_BUCKET: ${{ secrets.EVAL_R2_BUCKET }}
+          EVAL_R2_CDN_BASE_URL: ${{ secrets.EVAL_R2_CDN_BASE_URL }}
+        run: bun apps/eval/scripts/weekly-report.ts /tmp/eval-report.html
+
+      - name: Upload report as artifact
+        if: success()
+        uses: actions/upload-artifact@v4
+        with:
+          name: eval-report-${{ github.run_id }}
+          path: /tmp/eval-report.html

.github/workflows/pr-title.yml

@@ -0,0 +1,20 @@
+name: PR Conventional Commit Validation
+
+on:
+  pull_request:
+    types: [opened, edited]
+
+permissions:
+  pull-requests: write
+  issues: write
+  contents: read
+
+jobs:
+  validate-pr-title:
+    runs-on: ubuntu-latest
+    steps:
+      - name: PR Conventional Commit Validation
+        uses: ytanikin/pr-conventional-commits@1.5.1
+        with:
+          task_types: '["feat","fix","docs","test","ci","refactor","perf","chore","revert","build"]'
+          custom_labels: '{"feat": "feature", "fix": "fix", "docs": "documentation", "test": "test", "ci": "CI/CD", "refactor": "refactor", "perf": "performance", "chore": "chore", "revert": "revert", "wip": "WIP"}'

.github/workflows/release-agent-extension.yml

@@ -0,0 +1,148 @@
+name: Release BrowserOS Extension
+
+on:
+  workflow_dispatch:
+
+concurrency:
+  group: release-agent-extension
+  cancel-in-progress: false
+
+jobs:
+  release:
+    if: github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+    defaults:
+      run:
+        working-directory: packages/browseros-agent/apps/agent
+
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - uses: oven-sh/setup-bun@v2
+
+      - name: Install dependencies
+        run: bun ci
+        working-directory: packages/browseros-agent
+
+      - name: Build and zip extension
+        run: bun run codegen && bun run zip
+        env:
+          VITE_PUBLIC_BROWSEROS_API: https://api.browseros.com
+
+      - name: Get version and zip path
+        id: version
+        run: |
+          echo "version=$(node -p "require('./package.json').version")" >> "$GITHUB_OUTPUT"
+          echo "release_sha=$(git rev-parse HEAD)" >> "$GITHUB_OUTPUT"
+          ZIP_FILE=$(ls "$(pwd)/dist/"*-chrome.zip | head -n 1)
+          echo "zip_path=$ZIP_FILE" >> "$GITHUB_OUTPUT"
+          echo "zip_name=$(basename "$ZIP_FILE")" >> "$GITHUB_OUTPUT"
+
+      - name: Generate release notes
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          AGENT_PATH="packages/browseros-agent/apps/agent"
+          CURRENT_TAG="agent-extension-v${{ steps.version.outputs.version }}"
+          PREV_TAG=$(git tag -l "agent-extension-v*" --sort=-v:refname | grep -v "^${CURRENT_TAG}$" | head -n 1)
+
+          if [ -z "$PREV_TAG" ]; then
+            echo "Initial release" > /tmp/release-notes.md
+          else
+            COMMITS=$(git log "$PREV_TAG"..HEAD --pretty=format:"%H" -- "$AGENT_PATH")
+
+            if [ -z "$COMMITS" ]; then
+              echo "No notable changes." > /tmp/release-notes.md
+            else
+              echo "## What's Changed" > /tmp/release-notes.md
+              echo "" >> /tmp/release-notes.md
+
+              while IFS= read -r SHA; do
+                SUBJECT=$(git log -1 --pretty=format:"%s" "$SHA")
+                PR_NUM=$(gh api "/repos/${{ github.repository }}/commits/${SHA}/pulls" --jq '.[0].number // empty' 2>/dev/null)
+
+                # Skip PR number if already in the commit subject (squash merges include it)
+                if [ -n "$PR_NUM" ] && ! echo "$SUBJECT" | grep -qF "(#${PR_NUM})"; then
+                  echo "- ${SUBJECT} (#${PR_NUM})" >> /tmp/release-notes.md
+                else
+                  echo "- ${SUBJECT}" >> /tmp/release-notes.md
+                fi
+              done <<< "$COMMITS"
+            fi
+          fi
+        working-directory: ${{ github.workspace }}
+
+      - name: Create GitHub release
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          TAG="agent-extension-v${{ steps.version.outputs.version }}"
+          RELEASE_SHA="${{ steps.version.outputs.release_sha }}"
+          TITLE="BrowserOS Extension - v${{ steps.version.outputs.version }}"
+
+          if git rev-parse "$TAG" >/dev/null 2>&1; then
+            echo "Tag $TAG already exists, skipping tag creation"
+          else
+            git tag "$TAG" "$RELEASE_SHA"
+          fi
+
+          if git ls-remote --tags origin "$TAG" | grep -q "$TAG"; then
+            echo "Tag $TAG already on remote, skipping push"
+          else
+            git push origin "$TAG"
+          fi
+
+          if gh release view "$TAG" >/dev/null 2>&1; then
+            echo "Release $TAG already exists, updating"
+            gh release edit "$TAG" --title "$TITLE" --notes-file /tmp/release-notes.md
+            gh release upload "$TAG" "${{ steps.version.outputs.zip_path }}" --clobber
+          else
+            gh release create "$TAG" \
+              --title "$TITLE" \
+              --notes-file /tmp/release-notes.md \
+              "${{ steps.version.outputs.zip_path }}"
+          fi
+        working-directory: ${{ github.workspace }}
+
+      - name: Update CHANGELOG.md via PR
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          VERSION="${{ steps.version.outputs.version }}"
+          DATE=$(date -u +"%Y-%m-%d")
+          BRANCH="docs/agent-extension-changelog-v${VERSION}"
+          CHANGELOG="packages/browseros-agent/apps/agent/CHANGELOG.md"
+
+          git checkout main
+
+          {
+            head -n 1 "$CHANGELOG"
+            echo ""
+            echo "## v${VERSION} (${DATE})"
+            echo ""
+            cat /tmp/release-notes.md
+            echo ""
+            tail -n +2 "$CHANGELOG"
+          } > /tmp/new-changelog.md
+          mv /tmp/new-changelog.md "$CHANGELOG"
+
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git checkout -b "$BRANCH"
+          git add "$CHANGELOG"
+          git commit -m "docs: update agent extension changelog for v${VERSION}"
+          git push origin "$BRANCH"
+
+          gh pr create \
+            --title "docs: update agent extension changelog for v${VERSION}" \
+            --body "Auto-generated changelog update for BrowserOS Extension v${VERSION}." \
+            --base main \
+            --head "$BRANCH"
+
+          gh pr merge "$BRANCH" --squash --auto || true
+        working-directory: ${{ github.workspace }}

.github/workflows/release-agent-sdk.yml

@@ -0,0 +1,168 @@
+name: Release BrowserOS Agent SDK
+
+on:
+  workflow_dispatch:
+
+concurrency:
+  group: release-agent-sdk
+  cancel-in-progress: false
+
+jobs:
+  publish:
+    if: github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+    defaults:
+      run:
+        working-directory: packages/browseros-agent/packages/agent-sdk
+
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - uses: oven-sh/setup-bun@v2
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version: "20"
+          registry-url: "https://registry.npmjs.org"
+
+      - name: Install dependencies
+        run: bun ci
+        working-directory: packages/browseros-agent
+
+      - name: Build
+        run: bun run build
+
+      - name: Test
+        run: bun test
+
+      - name: Get version
+        id: version
+        run: |
+          echo "version=$(node -p "require('./package.json').version")" >> "$GITHUB_OUTPUT"
+          echo "release_sha=$(git rev-parse HEAD)" >> "$GITHUB_OUTPUT"
+
+      - name: Generate release notes
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          SDK_PATH="packages/browseros-agent/packages/agent-sdk"
+          CURRENT_TAG="agent-sdk-v${{ steps.version.outputs.version }}"
+          # Find the previous tag, excluding the current version's tag
+          # (which may already exist from a prior failed run)
+          PREV_TAG=$(git tag -l "agent-sdk-v*" --sort=-v:refname | grep -v "^${CURRENT_TAG}$" | head -n 1)
+
+          if [ -z "$PREV_TAG" ]; then
+            echo "Initial release" > /tmp/release-notes.md
+          else
+            # Get commits scoped to the SDK directory
+            COMMITS=$(git log "$PREV_TAG"..HEAD --pretty=format:"%H" -- "$SDK_PATH")
+
+            if [ -z "$COMMITS" ]; then
+              echo "No notable changes." > /tmp/release-notes.md
+            else
+              echo "## What's Changed" > /tmp/release-notes.md
+              echo "" >> /tmp/release-notes.md
+
+              # For each commit, find the associated PR and format with author
+              CONTRIBUTORS=""
+              while IFS= read -r SHA; do
+                # Get commit subject and author
+                SUBJECT=$(git log -1 --pretty=format:"%s" "$SHA")
+                AUTHOR=$(git log -1 --pretty=format:"%an" "$SHA")
+                GITHUB_USER=$(gh api "/repos/${{ github.repository }}/commits/${SHA}" --jq '.author.login // empty' 2>/dev/null)
+
+                # Find associated PR number
+                PR_NUM=$(gh api "/repos/${{ github.repository }}/commits/${SHA}/pulls" --jq '.[0].number // empty' 2>/dev/null)
+
+                # Format line: skip PR number if already in the commit subject
+                # (squash merges include "(#123)" in the subject automatically)
+                if [ -n "$PR_NUM" ] && ! echo "$SUBJECT" | grep -qF "(#${PR_NUM})"; then
+                  echo "- ${SUBJECT} (#${PR_NUM})" >> /tmp/release-notes.md
+                else
+                  echo "- ${SUBJECT}" >> /tmp/release-notes.md
+                fi
+              done <<< "$COMMITS"
+            fi
+          fi
+        working-directory: ${{ github.workspace }}
+
+      - name: Publish
+        run: npm publish --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+      - name: Create GitHub release
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          TAG="agent-sdk-v${{ steps.version.outputs.version }}"
+          RELEASE_SHA="${{ steps.version.outputs.release_sha }}"
+          TITLE="BrowserOS Agent SDK - v${{ steps.version.outputs.version }}"
+
+          # Create or reuse tag (idempotent for re-runs)
+          if git rev-parse "$TAG" >/dev/null 2>&1; then
+            echo "Tag $TAG already exists, skipping tag creation"
+          else
+            git tag "$TAG" "$RELEASE_SHA"
+          fi
+
+          # Push tag (skip if already on remote)
+          if git ls-remote --tags origin "$TAG" | grep -q "$TAG"; then
+            echo "Tag $TAG already on remote, skipping push"
+          else
+            git push origin "$TAG"
+          fi
+
+          # Create or update release
+          if gh release view "$TAG" >/dev/null 2>&1; then
+            echo "Release $TAG already exists, updating"
+            gh release edit "$TAG" --title "$TITLE" --notes-file /tmp/release-notes.md
+          else
+            gh release create "$TAG" --title "$TITLE" --notes-file /tmp/release-notes.md
+          fi
+        working-directory: ${{ github.workspace }}
+
+      - name: Update CHANGELOG.md via PR
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          VERSION="${{ steps.version.outputs.version }}"
+          DATE=$(date -u +"%Y-%m-%d")
+          BRANCH="docs/agent-sdk-changelog-v${VERSION}"
+          CHANGELOG="packages/browseros-agent/packages/agent-sdk/CHANGELOG.md"
+
+          # Return to main before branching
+          git checkout main
+
+          # Use head/tail to safely insert without sed quoting issues
+          {
+            head -n 1 "$CHANGELOG"
+            echo ""
+            echo "## v${VERSION} (${DATE})"
+            echo ""
+            cat /tmp/release-notes.md
+            echo ""
+            tail -n +2 "$CHANGELOG"
+          } > /tmp/new-changelog.md
+          mv /tmp/new-changelog.md "$CHANGELOG"
+
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git checkout -b "$BRANCH"
+          git add "$CHANGELOG"
+          git commit -m "docs: update agent-sdk changelog for v${VERSION}"
+          git push origin "$BRANCH"
+
+          gh pr create \
+            --title "docs: update agent-sdk changelog for v${VERSION}" \
+            --body "Auto-generated changelog update for BrowserOS Agent SDK v${VERSION}." \
+            --base main \
+            --head "$BRANCH"
+
+          gh pr merge "$BRANCH" --squash --auto || true
+        working-directory: ${{ github.workspace }}

.github/workflows/release-cli.yml

@@ -0,0 +1,161 @@
+name: Release BrowserOS CLI
+
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: "Release version (e.g. 0.1.0)"
+        required: true
+        type: string
+
+concurrency:
+  group: release-cli
+  cancel-in-progress: false
+
+jobs:
+  release:
+    if: github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    environment: release-core
+    permissions:
+      contents: write
+      pull-requests: write
+    defaults:
+      run:
+        working-directory: packages/browseros-agent/apps/cli
+
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-go@v5
+        with:
+          go-version-file: packages/browseros-agent/apps/cli/go.mod
+
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: "1.3.6"
+
+      - name: Run tests
+        run: make test
+
+      - name: Run vet
+        run: make vet
+
+      - name: Build all platforms
+        run: make release VERSION=${{ inputs.version }} POSTHOG_API_KEY=${{ secrets.POSTHOG_API_KEY }}
+
+      - name: Install dependencies
+        run: bun install
+        working-directory: packages/browseros-agent
+
+      - name: Upload to CDN
+        env:
+          R2_ACCOUNT_ID: ${{ secrets.R2_ACCOUNT_ID }}
+          R2_ACCESS_KEY_ID: ${{ secrets.R2_ACCESS_KEY_ID }}
+          R2_SECRET_ACCESS_KEY: ${{ secrets.R2_SECRET_ACCESS_KEY }}
+          R2_BUCKET: ${{ secrets.R2_BUCKET }}
+          R2_UPLOAD_PREFIX: cli
+          CLI_VERSION: ${{ inputs.version }}
+        run: |
+          bun scripts/build/cli.ts \
+            --release \
+            --version "$CLI_VERSION" \
+            --binaries-dir apps/cli/dist
+        working-directory: packages/browseros-agent
+
+      - name: Generate release notes
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          CLI_PATH="packages/browseros-agent/apps/cli"
+          TAG="browseros-cli-v${{ inputs.version }}"
+          CHANGELOG_FILE="/tmp/release-changelog.md"
+          PREV_TAG=$(git tag -l "browseros-cli-v*" --sort=-v:refname | grep -v "^${TAG}$" | head -n 1)
+
+          if [ -z "$PREV_TAG" ]; then
+            echo "Initial release of browseros-cli." > "$CHANGELOG_FILE"
+          else
+            COMMITS=$(git log "$PREV_TAG"..HEAD --pretty=format:"%H" -- "$CLI_PATH")
+
+            if [ -z "$COMMITS" ]; then
+              echo "No notable changes." > "$CHANGELOG_FILE"
+            else
+              echo "## What's Changed" > "$CHANGELOG_FILE"
+              echo "" >> "$CHANGELOG_FILE"
+
+              while IFS= read -r SHA; do
+                SUBJECT=$(git log -1 --pretty=format:"%s" "$SHA")
+                PR_NUM=$(gh api "/repos/${{ github.repository }}/commits/${SHA}/pulls" --jq '.[0].number // empty' 2>/dev/null)
+
+                if [ -n "$PR_NUM" ] && ! echo "$SUBJECT" | grep -qF "(#${PR_NUM})"; then
+                  echo "- ${SUBJECT} (#${PR_NUM})" >> "$CHANGELOG_FILE"
+                else
+                  echo "- ${SUBJECT}" >> "$CHANGELOG_FILE"
+                fi
+              done <<< "$COMMITS"
+            fi
+          fi
+
+          cat "$CHANGELOG_FILE" > /tmp/release-notes.md
+          cat >> /tmp/release-notes.md <<'EOF'
+
+          ## Install `browseros-cli`
+
+          ### npm / npx
+
+          ```bash
+          npx browseros-cli --help
+          npm install -g browseros-cli
+          ```
+
+          ### macOS / Linux
+
+          ```bash
+          curl -fsSL https://cdn.browseros.com/cli/install.sh | bash
+          ```
+
+          ### Windows
+
+          ```powershell
+          irm https://cdn.browseros.com/cli/install.ps1 | iex
+          ```
+
+          After install, run `browseros-cli init` to point the CLI at your BrowserOS MCP server.
+          EOF
+        working-directory: ${{ github.workspace }}
+
+      - name: Create tag and release
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          TAG="browseros-cli-v${{ inputs.version }}"
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+
+          if ! git rev-parse "$TAG" >/dev/null 2>&1; then
+            git tag -a "$TAG" -m "browseros-cli v${{ inputs.version }}"
+            git push origin "$TAG"
+          fi
+
+          CLI_DIST="packages/browseros-agent/apps/cli/dist"
+          gh release create "$TAG" \
+            --title "BrowserOS CLI - v${{ inputs.version }}" \
+            --notes-file /tmp/release-notes.md \
+            ${CLI_DIST}/*
+        working-directory: ${{ github.workspace }}
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          registry-url: "https://registry.npmjs.org"
+
+      - name: Publish to npm
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+        run: |
+          make npm-version VERSION=${{ inputs.version }}
+          cd npm
+          npm publish --access public

.github/workflows/release-server.yml

@@ -0,0 +1,147 @@
+name: Release BrowserOS Server
+
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: "Release version (e.g. 0.0.80)"
+        required: true
+        type: string
+
+concurrency:
+  group: release-server
+  cancel-in-progress: false
+
+jobs:
+  release:
+    if: github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    environment: release-core
+    permissions:
+      contents: write
+    defaults:
+      run:
+        working-directory: packages/browseros-agent
+
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: "1.3.6"
+
+      - name: Install dependencies
+        run: bun ci
+
+      - name: Prepare production env file
+        run: cp apps/server/.env.production.example apps/server/.env.production
+
+      - name: Validate version
+        id: version
+        env:
+          REQUESTED_VERSION: ${{ inputs.version }}
+        run: |
+          PACKAGE_VERSION=$(node -p "require('./apps/server/package.json').version")
+          echo "package_version=$PACKAGE_VERSION" >> "$GITHUB_OUTPUT"
+          echo "release_sha=$(git rev-parse HEAD)" >> "$GITHUB_OUTPUT"
+
+          if [ "$PACKAGE_VERSION" != "$REQUESTED_VERSION" ]; then
+            echo "Requested version $REQUESTED_VERSION does not match apps/server/package.json ($PACKAGE_VERSION)"
+            exit 1
+          fi
+
+      - name: Build release artifacts
+        run: bun run build:server:ci
+
+      - name: Verify release artifacts
+        run: |
+          mapfile -t ZIP_FILES < <(find dist/prod/server -maxdepth 1 -type f -name 'browseros-server-resources-*.zip' | sort)
+
+          if [ "${#ZIP_FILES[@]}" -eq 0 ]; then
+            echo "No server release zip files were produced"
+            exit 1
+          fi
+
+          printf 'Found release artifacts:\n%s\n' "${ZIP_FILES[@]}"
+
+      - name: Generate release notes
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          PACKAGE_VERSION: ${{ steps.version.outputs.package_version }}
+        run: |
+          SERVER_APP_PATH="packages/browseros-agent/apps/server"
+          SERVER_BUILD_DIR="packages/browseros-agent/scripts/build/server"
+          SERVER_BUILD_ENTRY="packages/browseros-agent/scripts/build/server.ts"
+          SERVER_RESOURCE_MANIFEST="packages/browseros-agent/scripts/build/config/server-prod-resources.json"
+          SERVER_WORKSPACE_PKG="packages/browseros-agent/package.json"
+          CURRENT_TAG="browseros-server-v$PACKAGE_VERSION"
+          PREV_TAG=$(git tag -l "browseros-server-v*" --sort=-v:refname | grep -v "^${CURRENT_TAG}$" | head -n 1)
+
+          if [ -z "$PREV_TAG" ]; then
+            echo "Initial release of browseros-server." > /tmp/release-notes.md
+          else
+            COMMITS=$(git log "$PREV_TAG"..HEAD --pretty=format:"%H" -- \
+              "$SERVER_APP_PATH" \
+              "$SERVER_BUILD_DIR" \
+              "$SERVER_BUILD_ENTRY" \
+              "$SERVER_RESOURCE_MANIFEST" \
+              "$SERVER_WORKSPACE_PKG")
+
+            if [ -z "$COMMITS" ]; then
+              echo "No notable changes." > /tmp/release-notes.md
+            else
+              echo "## What's Changed" > /tmp/release-notes.md
+              echo "" >> /tmp/release-notes.md
+
+              while IFS= read -r SHA; do
+                SUBJECT=$(git log -1 --pretty=format:"%s" "$SHA")
+                PR_NUM=$(gh api "/repos/${{ github.repository }}/commits/${SHA}/pulls" --jq '.[0].number // empty' 2>/dev/null)
+
+                if [ -n "$PR_NUM" ] && ! echo "$SUBJECT" | grep -qF "(#${PR_NUM})"; then
+                  echo "- ${SUBJECT} (#${PR_NUM})" >> /tmp/release-notes.md
+                else
+                  echo "- ${SUBJECT}" >> /tmp/release-notes.md
+                fi
+              done <<< "$COMMITS"
+            fi
+          fi
+        working-directory: ${{ github.workspace }}
+
+      - name: Create GitHub release
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          PACKAGE_VERSION: ${{ steps.version.outputs.package_version }}
+          RELEASE_SHA: ${{ steps.version.outputs.release_sha }}
+        run: |
+          TAG="browseros-server-v$PACKAGE_VERSION"
+          TITLE="BrowserOS Server - v$PACKAGE_VERSION"
+          mapfile -t ZIP_FILES < <(find packages/browseros-agent/dist/prod/server -maxdepth 1 -type f -name 'browseros-server-resources-*.zip' | sort)
+
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+
+          if git rev-parse "$TAG" >/dev/null 2>&1; then
+            echo "Tag $TAG already exists, skipping tag creation"
+          else
+            git tag -a "$TAG" -m "browseros-server v$PACKAGE_VERSION" "$RELEASE_SHA"
+          fi
+
+          if git ls-remote --tags origin "$TAG" | grep -q "$TAG"; then
+            echo "Tag $TAG already on remote, skipping push"
+          else
+            git push origin "$TAG"
+          fi
+
+          if gh release view "$TAG" >/dev/null 2>&1; then
+            echo "Release $TAG already exists, updating"
+            gh release edit "$TAG" --title "$TITLE" --notes-file /tmp/release-notes.md
+            gh release upload "$TAG" "${ZIP_FILES[@]}" --clobber
+          else
+            gh release create "$TAG" \
+              --title "$TITLE" \
+              --notes-file /tmp/release-notes.md \
+              "${ZIP_FILES[@]}"
+          fi
+        working-directory: ${{ github.workspace }}

.github/workflows/test.yml

@@ -0,0 +1,141 @@
+name: Tests
+
+on:
+  pull_request:
+    types:
+      - opened
+      - synchronize
+      - reopened
+      - ready_for_review
+    paths:
+      - .github/workflows/test.yml
+      - packages/browseros-agent/**
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+env:
+  BROWSEROS_APPIMAGE_URL: https://files.browseros.com/download/BrowserOS.AppImage
+
+jobs:
+  test:
+    name: Tests / ${{ matrix.suite }}
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    defaults:
+      run:
+        working-directory: packages/browseros-agent
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - suite: tools
+            test_path: tests/tools
+            junit_path: test-results/tools.xml
+          - suite: integration
+            test_path: tests/server.integration.test.ts
+            junit_path: test-results/integration.xml
+          - suite: sdk
+            test_path: tests/sdk
+            junit_path: test-results/sdk.xml
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v6
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+
+      - name: Install dependencies
+        run: bun ci
+
+      - name: Resolve BrowserOS cache key
+        id: browseros-cache-key
+        run: |
+          set -euo pipefail
+          headers="$(curl -fsSI "$BROWSEROS_APPIMAGE_URL")"
+          etag="$(printf '%s\n' "$headers" | awk 'BEGIN{IGNORECASE=1} /^etag:/ {sub(/\r$/, "", $2); gsub(/"/, "", $2); print $2; exit}')"
+          last_modified="$(printf '%s\n' "$headers" | awk 'BEGIN{IGNORECASE=1} /^last-modified:/ {$1=""; sub(/^ /, ""); sub(/\r$/, ""); print; exit}')"
+          raw_key="${etag:-$last_modified}"
+          if [ -z "$raw_key" ]; then
+            raw_key="$BROWSEROS_APPIMAGE_URL"
+          fi
+          cache_key="$(printf '%s' "$raw_key" | shasum -a 256 | awk '{print $1}')"
+          echo "key=browseros-appimage-${{ runner.os }}-$cache_key" >> "$GITHUB_OUTPUT"
+
+      - name: Restore BrowserOS cache
+        id: browseros-cache
+        uses: actions/cache@v4
+        with:
+          path: packages/browseros-agent/.ci/bin/BrowserOS.AppImage
+          key: ${{ steps.browseros-cache-key.outputs.key }}
+
+      - name: Download BrowserOS
+        if: steps.browseros-cache.outputs.cache-hit != 'true'
+        run: |
+          mkdir -p .ci/bin
+          curl -fsSL "$BROWSEROS_APPIMAGE_URL" -o .ci/bin/BrowserOS.AppImage
+          chmod +x .ci/bin/BrowserOS.AppImage
+
+      - name: Prepare BrowserOS wrapper
+        run: |
+          mkdir -p .ci/bin
+          cat > .ci/bin/browseros <<'EOF'
+          #!/usr/bin/env bash
+          set -euo pipefail
+          export APPIMAGE_EXTRACT_AND_RUN=1
+          exec "$(dirname "$0")/BrowserOS.AppImage" "$@"
+          EOF
+          chmod +x .ci/bin/browseros
+
+      - name: Create server env file
+        working-directory: packages/browseros-agent/apps/server
+        run: cp .env.example .env.development
+
+      - name: Run ${{ matrix.suite }} tests
+        id: test
+        env:
+          BROWSEROS_BINARY: ${{ github.workspace }}/packages/browseros-agent/.ci/bin/browseros
+          BROWSEROS_TEST_HEADLESS: "true"
+          BROWSEROS_TEST_EXTRA_ARGS: --no-sandbox --disable-dev-shm-usage
+        run: |
+          set +e
+          mkdir -p test-results
+          cd apps/server
+          bun run test:cleanup
+          bun --env-file=.env.development test "${{ matrix.test_path }}" --reporter=junit --reporter-outfile="../../${{ matrix.junit_path }}"
+          exit_code=$?
+          cd ../..
+          if [ ! -f "${{ matrix.junit_path }}" ]; then
+            cat > "${{ matrix.junit_path }}" <<EOF
+          <?xml version="1.0" encoding="UTF-8"?>
+          <testsuites tests="1" failures="1">
+            <testsuite name="${{ matrix.suite }}" tests="1" failures="1">
+              <testcase classname="workflow" name="${{ matrix.suite }} setup">
+                <failure message="Test run failed before JUnit output was written">See workflow logs for details.</failure>
+              </testcase>
+            </testsuite>
+          </testsuites>
+          EOF
+          fi
+          echo "exit_code=$exit_code" >> "$GITHUB_OUTPUT"
+
+      - name: Upload JUnit XML
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: junit-${{ matrix.suite }}
+          path: packages/browseros-agent/${{ matrix.junit_path }}
+
+      - name: Summarize suite result
+        if: always()
+        run: |
+          if [ "${{ steps.test.outputs.exit_code }}" = "0" ]; then
+            echo "### :white_check_mark: ${{ matrix.suite }} suite passed" >> "$GITHUB_STEP_SUMMARY"
+          else
+            echo "### :x: ${{ matrix.suite }} suite failed (exit code ${{ steps.test.outputs.exit_code }})" >> "$GITHUB_STEP_SUMMARY"
+            echo "" >> "$GITHUB_STEP_SUMMARY"
+            echo "See the uploaded \`junit-${{ matrix.suite }}\` artifact for details." >> "$GITHUB_STEP_SUMMARY"
+            exit 1
+          fi

.github/workflows/top-issues.yml

@@ -43,13 +43,23 @@ jobs:
             }
           ' -f owner='browseros-ai' -f repo='BrowserOS')
 
-          # Parse and sort issues by thumbs up count
-          sorted_issues=$(echo "$issues" | jq -r --arg ISSUE_NUMBER "$ISSUE_NUMBER" '
+          # Parse and sort RFC issues (titles containing [RFC])
+          sorted_rfcs=$(echo "$issues" | jq -r --arg ISSUE_NUMBER "$ISSUE_NUMBER" '
             .data.repository.issues.nodes
-            | map(select(.number != ($ISSUE_NUMBER | tonumber)))
+            | map(select(.number != ($ISSUE_NUMBER | tonumber) and (.title | contains("[RFC]"))))
             | sort_by(-.reactions.totalCount)
             | to_entries
-            | map("\(.key + 1). [\(.value.title)](\(.value.url)) - \(.value.reactions.totalCount) 👍")
+            | map("\(.key + 1). [\(.value.title)](\(.value.url)) — \(.value.reactions.totalCount) 👍")
+            | join("\n")
+          ')
+
+          # Parse and sort regular issues (excluding RFCs)
+          sorted_issues=$(echo "$issues" | jq -r --arg ISSUE_NUMBER "$ISSUE_NUMBER" '
+            .data.repository.issues.nodes
+            | map(select(.number != ($ISSUE_NUMBER | tonumber) and (.title | contains("[RFC]") | not)))
+            | sort_by(-.reactions.totalCount)
+            | to_entries
+            | map("\(.key + 1). [\(.value.title)](\(.value.url)) — \(.value.reactions.totalCount) 👍")
             | join("\n")
           ')
 
@@ -57,21 +67,38 @@ jobs:
           current_time=$(date -u +"%Y-%m-%d %H:%M:%S UTC")
 
           {
-            echo "# 👍 Top Issues and Features by Votes"
+            echo "# Community Roadmap"
             echo ""
             echo "This list is automatically updated every hour based on 👍 reactions."
             echo ""
-            echo "## How to Use This List"
+            echo "## How to Vote"
             echo ""
-            echo "**👍 Upvote features you want** - Items with more votes get prioritized."
+            echo "| Action | What it does |"
+            echo "|--------|--------------|"
+            echo "| 👍 on an issue | Adds your vote — we prioritize by vote count |"
+            echo "| 💬 Comment | Your feedback shapes what we build |"
             echo ""
             echo "**Don't see what you need?** Create a new [feature request](https://github.com/browseros-ai/BrowserOS/issues/new) or [bug report](https://github.com/browseros-ai/BrowserOS/issues/new)."
             echo ""
-            echo "Thank you for helping us prioritize!"
-            echo ""
             echo "**Last updated:** $current_time"
             echo ""
-            echo "## Top Issues"
+            echo "---"
+            echo ""
+            echo "## 📣 RFCs — We Need Your Input"
+            echo ""
+            echo "> **These proposals are in review.** Your vote and comments directly influence what gets built."
+            echo ">"
+            echo "> 👍 = Yes, build this  |  💬 = Share your use case or feedback"
+            echo ""
+            if [ -n "$sorted_rfcs" ]; then
+              echo "$sorted_rfcs"
+            else
+              echo "*No active RFCs right now. Check back soon!*"
+            fi
+            echo ""
+            echo "---"
+            echo ""
+            echo "## Top Issues & Feature Requests"
             echo ""
             echo "$sorted_issues"
             echo ""

.github/workflows/update-agent-submodule.yml

@@ -1,41 +0,0 @@
-name: Update Agent Submodule
-
-on:
-  schedule:
-    # Run every hour
-    - cron: "0 * * * *"
-  # Allow manual triggering for testing
-  workflow_dispatch:
-
-permissions:
-  contents: write
-
-concurrency:
-  group: submodule-update
-  cancel-in-progress: false
-
-jobs:
-  update-submodule:
-    runs-on: ubuntu-latest
-    # Only run on the main repository, not on forks
-    if: github.repository == 'browseros-ai/BrowserOS'
-
-    steps:
-      - name: Checkout repository with submodules
-        uses: actions/checkout@v4
-        with:
-          submodules: true
-          token: ${{ secrets.GITHUB_TOKEN }}
-
-      - name: Configure git
-        run: |
-          git config user.name "Felarof"
-          git config user.email "nithin.sonti@gmail.com"
-
-      - name: Update agent submodule
-        run: |
-          bash scripts/update-submodule.sh main
-
-      - name: Push changes
-        run: |
-          git push origin main

.gitignore

@@ -22,3 +22,12 @@
 nxtscape-cli-access.json
 gclient.json
 .env
+.grove/
+AGENTS.md
+**/resources/binaries/
+
+packages/browseros/build/tools/
+
+# AI SDK DevTools traces
+.devtools/
+.omc/

.gitmodules

@@ -1,4 +0,0 @@
-[submodule "packages/browseros-agent"]
-	path = packages/browseros-agent
-	url = https://github.com/browseros-ai/BrowserOS-agent.git
-	branch = main

.vscode/settings.json

@@ -0,0 +1,4 @@
+{
+  "terminal.integrated.tabs.title": "${sequence} ${process}",
+  "terminal.integrated.tabs.description": "${cwd}"
+}

README.md

@@ -6,6 +6,7 @@
 [![Slack](https://img.shields.io/badge/Slack-Join%20us-4A154B?logo=slack&logoColor=white)](https://dub.sh/browserOS-slack)
 [![Twitter](https://img.shields.io/twitter/follow/browserOS_ai?style=social)](https://twitter.com/browseros_ai)
 [![License: AGPL v3](https://img.shields.io/badge/License-AGPL%20v3-blue.svg)](LICENSE)
+[![Docs](https://img.shields.io/badge/Docs-docs.browseros.com-blue)](https://docs.browseros.com)
 <br></br>
 <a href="https://files.browseros.com/download/BrowserOS.dmg">
   <img src="https://img.shields.io/badge/Download-macOS-black?style=flat&logo=apple&logoColor=white" alt="Download for macOS (beta)" />
@@ -22,125 +23,183 @@
 <br />
 </div>
 
-## 
-🌐 BrowserOS is an open-source chromium fork that runs AI agents natively. **Your open-source, privacy-first alternative to ChatGPT Atlas, Perplexity Comet, Dia**.
+BrowserOS is an open-source Chromium fork that runs AI agents natively. **The privacy-first alternative to ChatGPT Atlas, Perplexity Comet, and Dia.**
 
-🔒 Privacy first - use your own API keys or run local models with Ollama. Your data stays on your computer.
+Use your own API keys or run local models with Ollama. Your data never leaves your machine.
 
-💡 Join our [Discord](https://discord.gg/YKwjt5vuKr) or [Slack](https://dub.sh/browserOS-slack) and help us build! Have feature requests? [Suggest here](https://github.com/browseros-ai/BrowserOS/issues/99).
+> **[Documentation](https://docs.browseros.com)** · **[Discord](https://discord.gg/YKwjt5vuKr)** · **[Slack](https://dub.sh/browserOS-slack)** · **[Twitter](https://x.com/browserOS_ai)** · **[Feature Requests](https://github.com/browseros-ai/BrowserOS/issues/99)**
 
-## Quick start
+## Quick Start
 
-1. Download and install BrowserOS:
-   - [macOS](https://files.browseros.com/download/BrowserOS.dmg)
-   - [Windows](https://files.browseros.com/download/BrowserOS_installer.exe)
-   - [Linux (AppImage)](https://files.browseros.com/download/BrowserOS.AppImage)
-   - [Linux (Debian)](https://cdn.browseros.com/download/BrowserOS.deb)
+1. **Download and install** BrowserOS — [macOS](https://files.browseros.com/download/BrowserOS.dmg) · [Windows](https://files.browseros.com/download/BrowserOS_installer.exe) · [Linux (AppImage)](https://files.browseros.com/download/BrowserOS.AppImage) · [Linux (Debian)](https://cdn.browseros.com/download/BrowserOS.deb)
+2. **Import your Chrome data** (optional) — bookmarks, passwords, extensions all carry over
+3. **Connect your AI provider** — Claude, OpenAI, Gemini, ChatGPT Pro via OAuth, or local models via Ollama/LM Studio
 
-2. Import your Chrome data (optional)
+## Features
 
-3. Connect your AI provider (OpenAI, Anthropic, or local models via Ollama/LMStudio)
-
-4. Start automating!
-
-## What makes BrowserOS special
-- 🏠 Feels like home - same familiar interface as Google Chrome, works with all your extensions
-- 🤖 AI agents that run on YOUR browser, not in the cloud
-- 🔒 Privacy first - bring your own keys or use local models with Ollama. Your browsing history stays on your computer
-- 🚀 Open source and community driven - see exactly what's happening under the hood
-- 🤝 BrowserOS as MCP server - you can install our MCP server and use the browser from within `claude-code` or `gemini-cli`.
-- 🛡️ Built-in AI ad blocker that works across more scenarios!  
+| Feature | Description | Docs |
+|---------|-------------|------|
+| **AI Agent** | 53+ browser automation tools — navigate, click, type, extract data, all with natural language | [Guide](https://docs.browseros.com/getting-started) |
+| **MCP Server** | Control the browser from Claude Code, Gemini CLI, or any MCP client | [Setup](https://docs.browseros.com/features/use-with-claude-code) |
+| **Workflows** | Build repeatable browser automations with a visual graph builder | [Docs](https://docs.browseros.com/features/workflows) |
+| **Cowork** | Combine browser automation with local file operations — research the web, save reports to your folder | [Docs](https://docs.browseros.com/features/cowork) |
+| **Scheduled Tasks** | Run agents on autopilot — daily, hourly, or every few minutes | [Docs](https://docs.browseros.com/features/scheduled-tasks) |
+| **Memory** | Persistent memory across conversations — your assistant remembers context over time | [Docs](https://docs.browseros.com/features/memory) |
+| **SOUL.md** | Define your AI's personality and instructions in a single markdown file | [Docs](https://docs.browseros.com/features/soul-md) |
+| **LLM Hub** | Compare Claude, ChatGPT, and Gemini responses side-by-side on any page | [Docs](https://docs.browseros.com/features/llm-chat-hub) |
+| **40+ App Integrations** | Gmail, Slack, GitHub, Linear, Notion, Figma, Salesforce, and more via MCP | [Docs](https://docs.browseros.com/features/connect-apps) |
+| **Vertical Tabs** | Side-panel tab management — stay organized even with 100+ tabs open | [Docs](https://docs.browseros.com/features/vertical-tabs) |
+| **Ad Blocking** | uBlock Origin + Manifest V2 support — [10x more protection](https://docs.browseros.com/features/ad-blocking) than Chrome | [Docs](https://docs.browseros.com/features/ad-blocking) |
+| **Cloud Sync** | Sync browser config and agent history across devices | [Docs](https://docs.browseros.com/features/sync) |
+| **Skills** | Custom instruction sets that shape how your AI assistant behaves | [Docs](https://docs.browseros.com/features/skills) |
+| **Smart Nudges** | Contextual suggestions to connect apps and use features at the right moment | [Docs](https://docs.browseros.com/features/smart-nudges) |
 
 ## Demos
 
-### 🤖 BrowserOS agent in action
+### BrowserOS agent in action
 [![BrowserOS agent in action](docs/videos/browserOS-agent-in-action.gif)](https://www.youtube.com/watch?v=SoSFev5R5dI)
 <br/><br/>
 
-### 🎇 Install [BrowserOS as MCP](https://docs.browseros.com/browseros-mcp/how-to-guide) and control it from `claude-code`
+### Install [BrowserOS as MCP](https://docs.browseros.com/features/use-with-claude-code) and control it from `claude-code`
 
 https://github.com/user-attachments/assets/c725d6df-1a0d-40eb-a125-ea009bf664dc
 
 <br/><br/>
 
-### 💬 Use BrowserOS to chat
+### Use BrowserOS to chat
 
 https://github.com/user-attachments/assets/726803c5-8e36-420e-8694-c63a2607beca
 
 <br/><br/>
 
-### ⚡ Use BrowserOS to scrape data
+### Use BrowserOS to scrape data
 
 https://github.com/user-attachments/assets/9f038216-bc24-4555-abf1-af2adcb7ebc0
 
 <br/><br/>
 
-## Why We're Building BrowserOS
+## Install `browseros-cli`
 
-For the first time since Netscape pioneered the web in 1994, AI gives us the chance to completely reimagine the browser. We've seen tools like Cursor deliver 10x productivity gains for developers—yet everyday browsing remains frustratingly archaic.
+Use `browseros-cli` to launch and control BrowserOS from the terminal or from AI coding agents like Claude Code.
 
-You're likely juggling 70+ tabs, battling your browser instead of having it assist you. Routine tasks, like ordering something from amazon or filling a form should be handled seamlessly by AI agents.
+**macOS / Linux:**
 
-At BrowserOS, we're convinced that AI should empower you by automating tasks locally and securely—keeping your data private. We are building the best browser for this future!
+```bash
+curl -fsSL https://cdn.browseros.com/cli/install.sh | bash
+```
 
-## How we compare
+**Windows:**
 
-<details>
-<summary><b>vs Chrome</b></summary>
-<br>
-While we're grateful for Google open-sourcing Chromium, but Chrome hasn't evolved much in 10 years. No AI features, no automation, no MCP support.
-</details>
+```powershell
+irm https://cdn.browseros.com/cli/install.ps1 | iex
+```
 
-<details>
-<summary><b>vs Brave</b></summary>
-<br>
-We love what Brave started, but they've spread themselves too thin with crypto, search, VPNs. We're laser-focused on AI-powered browsing.
-</details>
+After install, run `browseros-cli init` to connect the CLI to your running BrowserOS instance.
 
-<details>
-<summary><b>vs Arc/Dia</b></summary>
-<br>
-Many loved Arc, but it was closed source. When they abandoned users, there was no recourse. We're 100% open source - fork it anytime!
-</details>
+## LLM Providers
 
-<details>
-<summary><b>vs Perplexity Comet</b></summary>
-<br>
-They're a search/ad company. Your browser history becomes their product. We keep everything local.
-</details>
+BrowserOS works with any LLM. Bring your own keys, use OAuth, or run models locally.
 
-<details>
-<summary><b>vs ChatGPT Atlas</b></summary>
-<br>
-Your browsing data could be used for ads or to train their models. We keep your history and agent interactions strictly local.
-</details>
+| Provider | Type | Auth |
+|----------|------|------|
+| Kimi K2.5 | Cloud (default) | Built-in |
+| ChatGPT Pro/Plus | Cloud | [OAuth](https://docs.browseros.com/features/chatgpt) |
+| GitHub Copilot | Cloud | [OAuth](https://docs.browseros.com/features/github-copilot) |
+| Qwen Code | Cloud | [OAuth](https://docs.browseros.com/features/qwen-code) |
+| Claude (Anthropic) | Cloud | API key |
+| GPT-4o / o3 (OpenAI) | Cloud | API key |
+| Gemini (Google) | Cloud | API key |
+| Azure OpenAI | Cloud | API key |
+| AWS Bedrock | Cloud | IAM credentials |
+| OpenRouter | Cloud | API key |
+| Ollama | Local | [Setup](https://docs.browseros.com/features/ollama) |
+| LM Studio | Local | [Setup](https://docs.browseros.com/features/lm-studio) |
+
+## How We Compare
+
+| | BrowserOS | Chrome | Brave | Dia | Comet | Atlas |
+|---|:---:|:---:|:---:|:---:|:---:|:---:|
+| Open Source | ✅ | ❌ | ✅ | ❌ | ❌ | ❌ |
+| AI Agent | ✅ | ❌ | ❌ | ❌ | ✅ | ✅ |
+| MCP Server | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
+| Visual Workflows | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
+| Cowork (files + browser) | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
+| Scheduled Tasks | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
+| Bring Your Own Keys | ✅ | ❌ | ✅ | ❌ | ❌ | ❌ |
+| Local Models (Ollama) | ✅ | ❌ | ✅ | ❌ | ❌ | ❌ |
+| Local-first Privacy | ✅ | ❌ | ✅ | ❌ | ❌ | ❌ |
+| Ad Blocking (MV2) | ✅ | ❌ | ✅ | ❌ | ✅ | ❌ |
+
+**Detailed comparisons:**
+- [BrowserOS vs Chrome DevTools MCP](https://docs.browseros.com/comparisons/chrome-devtools-mcp) — developer-focused comparison for browser automation
+- [BrowserOS vs Claude Cowork](https://docs.browseros.com/comparisons/claude-cowork) — getting real work done with AI
+- [BrowserOS vs OpenClaw](https://docs.browseros.com/comparisons/openclaw) — everyday AI assistance
+
+## Architecture
+
+BrowserOS is a monorepo with two main subsystems: the **browser** (Chromium fork) and the **agent platform** (TypeScript/Go).
+
+```
+BrowserOS/
+├── packages/browseros/              # Chromium fork + build system (Python)
+│   ├── chromium_patches/            # Patches applied to Chromium source
+│   ├── build/                       # Build CLI and modules
+│   └── resources/                   # Icons, entitlements, signing
+│
+├── packages/browseros-agent/        # Agent platform (TypeScript/Go)
+│   ├── apps/
+│   │   ├── server/                  # MCP server + AI agent loop (Bun)
+│   │   ├── agent/                   # Browser extension UI (WXT + React)
+│   │   ├── cli/                     # CLI tool (Go)
+│   │   ├── eval/                    # Benchmark framework
+│   │   └── controller-ext/          # Chrome API bridge extension
+│   │
+│   └── packages/
+│       ├── agent-sdk/               # Node.js SDK (npm: @browseros-ai/agent-sdk)
+│       ├── cdp-protocol/            # CDP type bindings
+│       └── shared/                  # Shared constants
+```
+
+| Package | What it does |
+|---------|-------------|
+| [`packages/browseros`](packages/browseros/) | Chromium fork — patches, build system, signing |
+| [`apps/server`](packages/browseros-agent/apps/server/) | Bun server exposing 53+ MCP tools and running the AI agent loop |
+| [`apps/agent`](packages/browseros-agent/apps/agent/) | Browser extension — new tab, side panel chat, onboarding, settings |
+| [`apps/cli`](packages/browseros-agent/apps/cli/) | Go CLI — control BrowserOS from the terminal or AI coding agents |
+| [`apps/eval`](packages/browseros-agent/apps/eval/) | Benchmark framework — WebVoyager, Mind2Web evaluation |
+| [`agent-sdk`](packages/browseros-agent/packages/agent-sdk/) | Node.js SDK for browser automation with natural language |
+| [`cdp-protocol`](packages/browseros-agent/packages/cdp-protocol/) | Type-safe Chrome DevTools Protocol bindings |
 
 ## Contributing
 
-We'd love your help making BrowserOS better!
+We'd love your help making BrowserOS better! See our [Contributing Guide](CONTRIBUTING.md) for details.
 
-- 🐛 [Report bugs](https://github.com/nxtscape/nxtscape/issues)
-- 💡 [Suggest features](https://github.com/browseros-ai/BrowserOS/issues/99)
-- 💬 [Join Discord](https://discord.gg/YKwjt5vuKr)
-- 🐦 [Follow on Twitter](https://x.com/browserOS_ai)
+- [Report bugs](https://github.com/browseros-ai/BrowserOS/issues)
+- [Suggest features](https://github.com/browseros-ai/BrowserOS/issues/99)
+- [Join Discord](https://discord.gg/YKwjt5vuKr) · [Join Slack](https://dub.sh/browserOS-slack)
+- [Follow on Twitter](https://x.com/browserOS_ai)
+
+**Agent development** (TypeScript/Go) — see the [agent monorepo README](packages/browseros-agent/README.md) for setup instructions.
+
+**Browser development** (C++/Python) — requires ~100GB disk space. See [`packages/browseros`](packages/browseros/) for build instructions.
+
+## Credits
+
+- [ungoogled-chromium](https://github.com/ungoogled-software/ungoogled-chromium) — BrowserOS uses some patches for enhanced privacy. Thanks to everyone behind this project!
+- [The Chromium Project](https://www.chromium.org/) — at the core of BrowserOS, making it possible to exist in the first place.
 
 ## License
 
 BrowserOS is open source under the [AGPL-3.0 license](LICENSE).
 
-## Credits
+Copyright &copy; 2026 Felafax, Inc.
 
-- [ungoogled-chromium](https://github.com/ungoogled-software/ungoogled-chromium) - BrowserOS uses some patches for enhanced privacy. Thanks to everyone behind this project!
-- [The Chromium Project](https://www.chromium.org/) - At the core of BrowserOS, making it possible to exist in the first place.
-  
 ## Stargazers
+
 Thank you to all our supporters!
 
 [![Star History Chart](https://api.star-history.com/svg?repos=browseros-ai/BrowserOS&type=Date)](https://www.star-history.com/#browseros-ai/BrowserOS&Date)
 
-## 
 <p align="center">
 Built with ❤️ from San Francisco
 </p>
-
-

docs/appcast-x86_64.xml

@@ -1,28 +0,0 @@
-<?xml version="1.0" encoding="utf-8"?>
-<rss version="2.0" xmlns:sparkle="http://www.andymatuschak.org/xml-namespaces/sparkle"
-  xmlns:dc="http://purl.org/dc/elements/1.1/">
-  <channel>
-    <title>BrowserOS</title>
-    <link>https://cdn.browseros.com/appcast-x86_64.xml</link>
-    <description>Most recent changes with links to updates.</description>
-    <language>en</language>
-
-    <!-- Updates -->
-    <item>
-      <title>BrowserOS - 0.36.1</title>
-      <description sparkle:format="plain-text">
-      </description>
-      <sparkle:version>7554.49</sparkle:version>
-      <sparkle:shortVersionString>0.36.1</sparkle:shortVersionString>
-      <pubDate>Tue, 07 Jan 2026 12:00:00 +0000</pubDate>
-      <link>https://browseros.com</link>
-      <enclosure
-        url="http://cdn.browseros.com/releases/0.36.1/macos/BrowserOS_v0.36.1_x64.dmg"
-        sparkle:edSignature="JVLNnUlbItG2PDAu69qGuEh7f3dHYddOWS14VewhvKR4Uvm3ZZPkhh0226BNBitTmgtSCqi3wvM6jlB8yXr7DA=="
-        length="186025298"
-        type="application/octet-stream" />
-      <sparkle:minimumSystemVersion>10.15</sparkle:minimumSystemVersion>
-    </item>
-
-  </channel>
-</rss>

docs/appcast.xml

@@ -1,28 +0,0 @@
-<?xml version="1.0" encoding="utf-8"?>
-<rss version="2.0" xmlns:sparkle="http://www.andymatuschak.org/xml-namespaces/sparkle"
-  xmlns:dc="http://purl.org/dc/elements/1.1/">
-  <channel>
-    <title>BrowserOS</title>
-    <link>https://cdn.browseros.com/appcast.xml</link>
-    <description>Most recent changes with links to updates.</description>
-    <language>en</language>
-
-    <!-- Updates -->
-    <item>
-      <title>BrowserOS - 0.36.1</title>
-      <description sparkle:format="plain-text">
-      </description>
-      <sparkle:version>7554.49</sparkle:version>
-      <sparkle:shortVersionString>0.36.1</sparkle:shortVersionString>
-      <pubDate>Tue, 07 Jan 2026 12:00:00 +0000</pubDate>
-      <link>https://browseros.com</link>
-      <enclosure
-        url="http://cdn.browseros.com/releases/0.36.1/macos/BrowserOS_v0.36.1_arm64.dmg"
-        sparkle:edSignature="dYtYf77WFVgmzdkOtpEWkYCjKkVpXO7FrpR4hihPk+iCcj+JHO58t1SWXORphbM08xM3YziU8D5C4JUsGh7vBQ=="
-        length="173907590"
-        type="application/octet-stream" />
-      <sparkle:minimumSystemVersion>10.15</sparkle:minimumSystemVersion>
-    </item>
-
-  </channel>
-</rss>

docs/bring-your-own-keys/claude.mdx

@@ -1,28 +0,0 @@
----
-title: "Claude"
-description: "Configure BrowserOS to use Anthropic's Claude AI assistant"
----
-
-Claude Sonnet 3.7 and 4.0 are excellent for agent tasks. Great for complex reasoning and following instructions precisely.
-
-## Get your API key
-
-### Step 1: Go to Claude Console
-
-Visit [console.anthropic.com](https://console.anthropic.com/dashboard) and click **API keys** in the left sidebar.
-
-![Anthropic console API keys sidebar](/images/claude-api-keys.png)
-
-### Step 2: Create a key
-
-Click **Create Key**, name it, and click **Create Key** again. Copy the key that appears.
-
-![Create API key dialog](/images/claude-create-key.png)
-
-## Configure BrowserOS
-
-Navigate to `chrome://browseros/settings` or click the **Settings** icon on the new tab page, then click **USE** on the Claude card. Paste your API key and set your model. For Claude Sonnet 4.0, use model ID `claude-opus-4-20250514`, set **Context Window Size** to `128000`, and check **Supports Images**. Click **Save**.
-
-![Claude provider configuration](/images/claude-provider-config.png)
-
-Done! You're ready to use BrowserOS with Claude.

docs/bring-your-own-keys/gemini.mdx

@@ -1,47 +0,0 @@
----
-title: "Gemini"
-description: "Configure BrowserOS to use Google's Gemini AI model"
----
-
-Gemini 2.5 Flash is fast, powerful, and free. Google AI Studio gives you 20 requests per minute at no cost - perfect for BrowserOS.
-
-## Get your API key
-
-### Step 1: Go to Google AI Studio
-
-Visit [aistudio.google.com](https://aistudio.google.com) and click **Get API key** in the left sidebar.
-
-![Google AI Studio Get API key sidebar](/images/gemini-get-api-key.png)
-
-### Step 2: Create a new project
-
-Click **Create API key**, then name your project and click **Create key**.
-
-![Create API key dialog](/images/gemini-create-key.png)
-
-### Step 3: Copy your API key
-
-Your key will appear in the list. Click on it to copy.
-
-![Copy API key from list](/images/gemini-copy-key.png)
-
-## Configure BrowserOS
-
-### Step 1: Open LLM settings
-
-Navigate to `chrome://browseros/settings` or click the **Settings** icon on the new tab page, then click **USE** on the Gemini card.
-
-![BrowserOS settings with Gemini card](/images/gemini-settings-card.png)
-
-### Step 2: Configure your provider
-
-In the provider configuration:
-1. Set **Model ID** to `gemini-2.5-flash`
-2. Paste your API key in the **API Key** field
-3. Check **Supports Images**
-4. Set **Context Window Size** to `1000000` (1 million tokens)
-5. Click **Save**
-
-![Gemini provider configuration](/images/gemini-provider-config.png)
-
-Done! You're ready to use BrowserOS with Gemini.

docs/bring-your-own-keys/openai.mdx

@@ -1,32 +0,0 @@
----
-title: "OpenAI"
-description: "Configure BrowserOS to use OpenAI's GPT models"
----
-
-GPT-4.1 is powerful for complex agent tasks. If you need the best reasoning capabilities, OpenAI is a solid choice.
-
-## Get your API key
-
-### Step 1: Go to OpenAI Platform
-
-Visit [platform.openai.com](https://platform.openai.com), click the settings icon in the top right, then go to **API keys** in the left sidebar.
-
-![OpenAI platform API keys](/images/openai-api-keys.png)
-
-### Step 2: Create a new key
-
-Click **Create new secret key**, name it, and click **Create secret key**.
-
-![Create secret key dialog](/images/openai-create-key.png)
-
-### Step 3: Copy your key
-
-Copy the key that appears. Keep it safe - you won't be able to see it again.
-
-## Configure BrowserOS
-
-Navigate to `chrome://browseros/settings` or click the **Settings** icon on the new tab page, then click **USE** on the OpenAI card. Paste your API key and configure the settings based on your chosen model. For GPT-4.1, set **Context Window Size** to `128000` and check **Supports Images**. Click **Save**.
-
-![OpenAI provider configuration](/images/openai-provider-config.png)
-
-Done! You're ready to use BrowserOS with OpenAI.

docs/bring-your-own-keys/openrouter.mdx

@@ -1,34 +0,0 @@
----
-title: "Open Router"
-description: "Configure BrowserOS to use Open Router for access to multiple AI models"
----
-
-OpenRouter gives you access to 500+ models through one API. Try different models without managing multiple API keys.
-
-## Get your API key
-
-Visit [openrouter.ai](https://openrouter.ai), sign up, and create an API key. OpenRouter shows your key right on the homepage under "Get your API key".
-
-![OpenRouter get API key](/images/openrouter-get-api-key.png)
-
-## Configure BrowserOS
-
-### Step 1: Add OpenRouter provider
-
-Navigate to `chrome://browseros/settings` or click the **Settings** icon on the new tab page, then click **USE** on the OpenRouter card.
-
-![BrowserOS settings with OpenRouter card](/images/openrouter-settings-card.png)
-
-### Step 2: Pick a model
-
-Visit [openrouter.ai/models](https://openrouter.ai/models) and find the model you want. Click on it to copy the model ID (like `openai/gpt-4.1-mini`).
-
-![OpenRouter models page](/images/openrouter-models.png)
-
-### Step 3: Configure your provider
-
-In BrowserOS, paste the model ID into **Model ID** field. The model ID should be in the format shown under "Custom" (e.g., `openai/gpt-4.1-mini`). Paste your OpenRouter API key, set **Context Window Size** based on the model, and check **Supports Images** if the model supports it. Click **Save**.
-
-![OpenRouter provider configuration](/images/openrouter-provider-config.png)
-
-Done! You can switch between different models anytime by creating new providers with different model IDs.

docs/browseros-mcp/how-to-guide.mdx

@@ -1,61 +0,0 @@
----
-title: "BrowserOS as MCP"
-description: "Connect BrowserOS as an MCP server to Claude Code or Claude Desktop"
----
-
-## How to use `BrowserOS-mcp` on Claude Code
-
-1. Download binary from [BrowserOS.com](https://BrowserOS.com)
-2. Open BrowserOS and navigate to `chrome://browseros/settings` or click the **Settings** icon on the new tab page.
-3. Navigate to **MCP** in the sidebar and copy the MCP URL
-4. In your terminal, type the below command (Replace `<mcp_url>` with the MCP URL you copied above):
-   ```
-   claude mcp add --transport http browseros <mcp_url> --scope user
-   # example: claude mcp add --transport http browseros http://127.0.0.1:9226/mcp --scope user
-   ``` 
-5. Now start Claude Code: `claude --dangerously-skip-permissions` (so Claude doesn't ask for confirmation each time)
-6. Now, in Claude Code, type `Open amazon.com on browseros` to open the tab in BrowserOS.
-
-Here's a [loom video](https://www.loom.com/share/9a41b74f265649a2993c329b05f93b54?sid=009690dd-e1a0-47b9-9b41-abe544e90c78) capturing the above steps! 🥳
-
-### gemini-cli
-The steps are roughly the same as above, but to add the MCP server, run the following command:
-
-```
-gemini mcp add local-server <mcp_url> --transport http --scope user
-# example: gemini mcp add local-server http://127.0.0.1:9226/mcp --transport http --scope user
-```
-
----
-
-## How to add `BrowserOS-mcp` on Claude Desktop
-
-1. Download binary from [BrowserOS.com](https://BrowserOS.com)
-2. Open BrowserOS and navigate to `chrome://browseros/settings` or click the **Settings** icon on the new tab page. Navigate to **MCP** in the sidebar and note the port number (usually `9225`).
-3. Open your Claude Desktop config file: `/Users/<username>/Library/Application Support/Claude/claude_desktop_config.json`
-4. Add BrowserOS to your config (replace the port with the value shown in MCP settings page):
-```json
-{
-  "mcpServers": {
-    "browserOS": {
-      "command": "npx",
-      "args": ["mcp-remote", "http://127.0.0.1:<port>/mcp"]
-    }
-  }
-}
-```
-5. Restart Claude Desktop. You should see the MCP connection indicator showing BrowserOS is connected
-
----
-
-## Demo videos
-
-### better agentic loop for web app development
-[![Frontend dev demo](https://img.youtube.com/vi/vcSxzIIkg_0/0.jpg)](https://youtu.be/vcSxzIIkg_0)
-
-### claude-code + `BrowserOS-mcp` == agentic browser!
-[![Agentic tasks demo](https://img.youtube.com/vi/rPFx_Btajj0/0.jpg)](https://youtu.be/rPFx_Btajj0)
-
-### vibe coded HN clone in under 5 mintes
-[![vibe coding HN](https://img.youtube.com/vi/c-egH0R3ZTs/0.jpg)](https://youtu.be/c-egH0R3ZTs)
-

docs/changelog.mdx

@@ -0,0 +1,176 @@
+---
+title: "Changelog"
+description: "What's new in BrowserOS"
+---
+
+All notable changes to BrowserOS are documented here. For the full release history with download links, see our [GitHub Releases](https://github.com/browseros-ai/BrowserOS/releases).
+
+---
+
+## v0.42.0
+<sub>March 9, 2026</sub>
+
+- **SOUL.md** — Your assistant now has a soul. Tell it how you like to communicate, set boundaries, shape its personality — and it adapts on its own over time. The more you use it, the more it feels like *your* assistant. [Read more →](/features/soul)
+- **Vertical tabs** — One of the most requested features is here. BrowserOS now ships with vertical tabs by default. More screen space, better tab management, and a cleaner layout out of the box. Prefer horizontal? You can switch back anytime in settings. [Read more →](/features/vertical-tabs)
+- **Long-term memory** — Your assistant finally remembers you. Your name, your projects, what you talked about last week — it carries context across every conversation so you never have to repeat yourself. All stored locally on your machine. [Read more →](/features/memory)
+- **Chromium 146** — Updated to the latest Chromium release with all recent upstream fixes and security patches
+
+<Frame>
+  <img src="/images/changelog/0.42.0/soul-memory.png" alt="BrowserOS v0.42.0 SOUL.md feature for agent personalization" />
+</Frame>
+
+<Frame>
+  <img src="/images/changelog/0.42.0/vertical-tabs.png" alt="BrowserOS v0.42.0 vertical tabs toggle in settings" />
+</Frame>
+
+---
+
+## v0.41.0
+<sub>March 4, 2026</sub>
+
+- **New agent (v3)** — Completely redone from scratch. 2x faster, 2–3x better performance
+- **Tools — major upgrade** — Agent tools and MCP server both got a big overhaul. ~20 new tools (54 total) including file upload, save as PDF, background windows, and more. Connection with third-party coding agents (Claude Code, Codex, etc.) is much better now
+- **General fixes** — Better agent installation, bug fixes, and smoother experience overall
+- **Linux Debian packaging** — Fixed the remaining Debian packaging issues
+
+---
+
+## v0.40.1
+<sub>February 16, 2026</sub>
+
+- **Chromium 145** — Upgraded to the latest Chromium base with all recent upstream fixes and security patches
+- **Login session import improvements** — Importing login sessions is now more reliable
+- **Stability & reliability** — General improvements across the board
+
+---
+
+## v0.39.0
+<sub>February 3, 2026</sub>
+
+- **Sync** — Save your browser configuration, agent history, and scheduled tasks across machines. Your setup now follows you wherever you go
+- **App Connector redesign** — Connecting MCP apps is now easier. The new App Connector UI makes it simpler to discover, install, and manage your connected apps
+- **MCP port stability** — Additional fixes for users still experiencing port issues. More reliable connections across restarts
+- **Keyboard shortcuts** — Updated shortcuts to avoid conflicts with European keyboards
+
+<Frame>
+  <img src="/images/changelog/0.39.0-sync-mcp.png" alt="BrowserOS v0.39.0 featuring Sync and improved MCP connectors" />
+</Frame>
+
+---
+
+## v0.38.0
+<sub>January 28, 2026</sub>
+
+Bug fix and stability release.
+
+- **MCP port fix on Windows & Linux** — Fixed an issue with MCP port. Port now stays consistent across restarts and made it more reliable
+- **Settings fix** — Fixed `chrome.browser.settings` not working correctly. Settings should now persist and apply as expected
+- **Improved agent** — Made the agent more reliable and performant. General stability fixes across the agent loop
+
+---
+
+## v0.37.0
+<sub>January 21, 2026</sub>
+
+- **Workflows** — Build reliable, repeatable browser automations with a visual graph builder. Chat with the workflow agent to define step-by-step automation—ideal for complex tasks where ad-hoc prompts aren't enough. [Read more →](/features/workflows)
+
+<img src="/features/workflow/sample-workflow.png" alt="Workflows visual graph builder showing a data entry automation" />
+
+- **Cowork** — Describe an outcome, step away, and come back to finished work. Combine browser automation with local file operations—research on the web and save reports, scrape data and export to files, all in one task. [Read more →](/features/cowork)
+
+<img src="/features/cowork/cowork-research-example.png" alt="Agent researching Hacker News and generating an HTML report" />
+
+---
+
+## v0.36.3
+<sub>January 15, 2026</sub>
+
+- **Agent history** — Agent conversations are now saved automatically. View and resume them anytime from the Assistant panel
+
+<img src="/images/changelog/0.36.3/agent-history-highlight.png" alt="Agent history button in the Assistant panel" />
+
+<img src="/images/changelog/0.36.3/agent-history-example.png" alt="Agent history showing past conversations" />
+
+---
+
+## v0.36.2
+<sub>January 10, 2026</sub>
+
+Bug fix release focused on MCP stability.
+
+- **MCP server disconnect fix** — Fixed port handling issue causing MCP connections to drop unexpectedly
+
+---
+
+## v0.36.0
+<sub>January 8, 2026</sub>
+
+- **Agent personalization** — Add your own prompts to personalize the agent. Tweak its behavior, adjust how it responds, set your preferred formatting, and more
+- **Toolbar customization** — Hide the Hub chat and labels from the settings page to declutter your toolbar
+- **MCP server port stability** — The port now stays consistent through browser restarts, so you don't have to keep updating your MCP clients
+- **Fixed agent install/update issues** — The agent now handles installs and updates more proactively
+
+---
+
+## v0.35.0
+<sub>December 25, 2025</sub>
+
+- **Agent stability fixes** — Fixed bugs to make the agent loop much more reliable
+- **Gemini 3 support** — Gemini 3 now supported through OpenRouter and Google adapters
+- **Better error surfacing** — Error messages are now clearer
+
+---
+
+## v0.34.0
+<sub>December 20, 2025</sub>
+
+- **Third-party MCP server support** — Connect external MCP servers like Google Calendar, Notion, Google Docs, Gmail, and more. You can also connect your own custom MCP servers
+- **Gemini 3 support** — Gemini 3 Pro and Flash models now work with BrowserOS
+- **Windows icon fix** — The Windows icon now displays BrowserOS logo correctly
+- **Agent & UI improvements** — Various agent loop fixes and UI polish
+
+---
+
+## v0.33.0
+<sub>December 18, 2025</sub>
+
+- **OpenAI-compatible provider support** — Connect any OpenAI-compatible API endpoint
+- **Multi-window & multi-profile agent support** — Agent now works across multiple windows and browser profiles
+- **MCP server reliability** — Fixed connection drops and improved stability
+- **Agent reliability improvements** — General stability fixes
+
+---
+
+## v0.32.0
+<sub>December 12, 2025</sub>
+
+A complete revamp of BrowserOS.
+
+**New features:**
+- **New Agent** — Completely rebuilt agent: faster, smarter, and more reliable
+- **Agent Per Tab** — Run multiple agents in different tabs simultaneously
+- **Polished UI** — Fresh, cleaner interface design
+- **Manifest V2 Support** — Ad blockers like uBlock Origin work again
+- **Native Split View** — Work on two things side by side
+- **Chromium 142** — Updated to Chromium 142.0.7444.49
+- **Azure & AWS Bedrock** — Native support for Azure OpenAI and AWS Bedrock models
+
+**Breaking changes:**
+- Old agent will stop working — update required
+- LLM provider settings won't carry over — reconfiguration needed
+
+---
+
+## v0.30.0
+<sub>November 14, 2025</sub>
+
+- **Better text extraction** — Improved copy button in LLM Chat
+- **MCP server stability** — Improved connection reliability
+- **UI cleanup** — Unpinned extensions for cleaner look
+- **Third-party MCP fixes** — Fixed support for third-party MCP servers
+
+---
+
+<Note>
+For older releases, see the [full release history on GitHub](https://github.com/browseros-ai/BrowserOS/releases).
+</Note>

docs/comparisons/chrome-devtools-mcp.mdx

@@ -0,0 +1,201 @@
+---
+title: "Chrome DevTools MCP"
+description: "A developer-focused comparison of BrowserOS MCP and Chrome DevTools MCP for browser automation"
+---
+
+Both BrowserOS MCP and [Chrome DevTools MCP](https://github.com/ChromeDevTools/chrome-devtools-mcp) give AI agents control over a browser via the Model Context Protocol. But they're built for different scopes. Chrome DevTools MCP focuses on debugging and inspection, while BrowserOS MCP is a complete browser automation and app integration platform.
+
+This page breaks down the differences for developers evaluating which to use with Claude Code, Gemini CLI, Cursor, or any MCP client.
+
+---
+
+## At a Glance
+
+| | **BrowserOS MCP** | **Chrome DevTools MCP** |
+|---|---|---|
+| **Total MCP tools** | 53 | 29 |
+| **External app integrations** | 40+ (Gmail, Slack, GitHub, etc.) | None |
+| **Setup** | Copy URL from settings, works instantly | Requires `--remote-debugging-port` flag and separate server process |
+| **Browser session** | Your real browser with cookies, logins, extensions | Attached debug session (some sites block WebDriver-controlled browsers) |
+| **Architecture** | Built into the browser | External Node.js process connecting via CDP |
+
+---
+
+## Feature Comparison
+
+### Navigation & Tab Management
+
+| Feature | BrowserOS MCP | Chrome DevTools MCP |
+|---------|:---:|:---:|
+| Navigate to URL / back / forward / reload | `navigate_page` | `navigate_page` |
+| Open new tab | `new_page` | `new_page` |
+| Close tab | `close_page` | `close_page` |
+| List open tabs | `list_pages` | `list_pages` |
+| Switch to tab | `show_page` | `select_page` |
+| Hidden/background tabs | `new_hidden_page` | - |
+| Move tab between windows | `move_page` | - |
+| Get active/focused tab | `get_active_page` | - |
+| Wait for condition | - | `wait_for` |
+
+### Content & Observation
+
+| Feature | BrowserOS MCP | Chrome DevTools MCP |
+|---------|:---:|:---:|
+| Accessibility tree snapshot | `take_snapshot` | `take_snapshot` |
+| Enhanced structural snapshot | `take_enhanced_snapshot` | - |
+| Page content as Markdown | `get_page_content` | - |
+| Extract all page links | `get_page_links` | - |
+| Raw HTML / DOM access | `get_dom` | - |
+| Search DOM (text / CSS / XPath) | `search_dom` | - |
+| Screenshot | `take_screenshot` | `take_screenshot` |
+| Execute JavaScript | `evaluate_script` | `evaluate_script` |
+
+### Interaction & Input
+
+| Feature | BrowserOS MCP | Chrome DevTools MCP |
+|---------|:---:|:---:|
+| Click element | `click` | `click` |
+| Click at coordinates | `click_at` | - |
+| Type / fill text | `fill` | `fill` |
+| Fill entire form | - | `fill_form` |
+| Type text (raw keystrokes) | - | `type_text` |
+| Clear input | `clear` | - |
+| Hover | `hover` | `hover` |
+| Drag | `drag` | `drag` |
+| Press key / key combo | `press_key` | `press_key` |
+| Check / uncheck checkbox | `check` / `uncheck` | - |
+| Select dropdown option | `select_option` | - |
+| Focus element | `focus` | - |
+| Scroll (directional) | `scroll` | - |
+| Upload file | `upload_file` | `upload_file` |
+| Handle dialog (alert/confirm) | `handle_dialog` | `handle_dialog` |
+
+### File & Export
+
+| Feature | BrowserOS MCP | Chrome DevTools MCP |
+|---------|:---:|:---:|
+| Save page as PDF | `save_pdf` | - |
+| Save screenshot to disk | `save_screenshot` | - |
+| Download file via click | `download_file` | - |
+
+### Window Management
+
+| Feature | BrowserOS MCP | Chrome DevTools MCP |
+|---------|:---:|:---:|
+| List windows | `list_windows` | - |
+| Create window | `create_window` | - |
+| Create hidden window | `create_hidden_window` | - |
+| Close window | `close_window` | - |
+| Activate / focus window | `activate_window` | - |
+
+### Tab Groups
+
+| Feature | BrowserOS MCP | Chrome DevTools MCP |
+|---------|:---:|:---:|
+| List tab groups | `list_tab_groups` | - |
+| Create tab group | `group_tabs` | - |
+| Update group (title/color) | `update_tab_group` | - |
+| Ungroup tabs | `ungroup_tabs` | - |
+| Close tab group | `close_tab_group` | - |
+
+### Bookmarks
+
+| Feature | BrowserOS MCP | Chrome DevTools MCP |
+|---------|:---:|:---:|
+| List bookmarks | `get_bookmarks` | - |
+| Create bookmark / folder | `create_bookmark` | - |
+| Remove bookmark | `remove_bookmark` | - |
+| Update bookmark | `update_bookmark` | - |
+| Move bookmark | `move_bookmark` | - |
+| Search bookmarks | `search_bookmarks` | - |
+
+### History
+
+| Feature | BrowserOS MCP | Chrome DevTools MCP |
+|---------|:---:|:---:|
+| Search history | `search_history` | - |
+| Get recent history | `get_recent_history` | - |
+| Delete URL from history | `delete_history_url` | - |
+| Delete history range | `delete_history_range` | - |
+
+### Debugging & Performance
+
+| Feature | BrowserOS MCP | Chrome DevTools MCP |
+|---------|:---:|:---:|
+| Console messages | Coming soon | `get_console_message` / `list_console_messages` |
+| Network request inspection | Coming soon | `get_network_request` / `list_network_requests` |
+| Performance tracing | Coming soon | `performance_start_trace` / `performance_stop_trace` |
+| Performance analysis | Coming soon | `performance_analyze_insight` |
+| Memory snapshot | Coming soon | `take_memory_snapshot` |
+| Lighthouse audit | Coming soon | `lighthouse_audit` |
+| Device / network emulation | Coming soon | `emulate` |
+| Resize viewport | Coming soon | `resize_page` |
+
+### External App Integrations
+
+| Feature | BrowserOS MCP | Chrome DevTools MCP |
+|---------|:---:|:---:|
+| Gmail, Outlook | Yes | - |
+| Google Calendar, Outlook Calendar | Yes | - |
+| Slack, Discord, Teams, WhatsApp | Yes | - |
+| GitHub, GitLab | Yes | - |
+| Linear, Jira, Asana, Monday, ClickUp | Yes | - |
+| Notion, Google Docs/Sheets/Drive | Yes | - |
+| Figma, Canva | Yes | - |
+| Salesforce, HubSpot | Yes | - |
+| Shopify, Stripe | Yes | - |
+| 20+ more services | Yes | - |
+
+---
+
+## Setup Comparison
+
+<Tabs>
+  <Tab title="BrowserOS MCP">
+    BrowserOS MCP is built into the browser. No separate process, no debug flags.
+
+    ```bash
+    # One command, done
+    claude mcp add --transport http browseros http://127.0.0.1:9239/mcp --scope user
+    ```
+
+    The server URL is available at `chrome://browseros/mcp`. Copy it and connect.
+  </Tab>
+  <Tab title="Chrome DevTools MCP">
+    Chrome DevTools MCP requires launching Chrome with remote debugging enabled and running a separate Node.js server.
+
+    ```bash
+    # Step 1: Launch Chrome with debug port
+    /Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222
+
+    # Step 2: Install and run the MCP server
+    npx @anthropic-ai/chrome-devtools-mcp@latest
+
+    # Step 3: Connect your MCP client to the server
+    ```
+
+    Some sites may block sign-in when the browser is controlled via WebDriver (the default launch mechanism).
+  </Tab>
+</Tabs>
+
+---
+
+## Summary
+
+| Dimension | BrowserOS MCP | Chrome DevTools MCP |
+|-----------|:---:|:---:|
+| Browser automation tools | **54** | **29** |
+| External app integrations | **40+** | **0** |
+| Window management | Yes | No |
+| Tab groups | Yes | No |
+| Bookmarks & history | Yes | No |
+| File export (PDF, screenshots, downloads) | Yes | No |
+| Content extraction (Markdown, links, DOM) | Yes | No |
+| Console / network inspection | Coming soon | Yes |
+| Performance tracing & Lighthouse | Coming soon | Yes |
+| Memory snapshots | Coming soon | Yes |
+| Device emulation | Coming soon | Yes |
+| Setup complexity | Copy URL | Debug port + Node server |
+| Browser session | Real (cookies, extensions) | Debug-attached (WebDriver flags) |
+
+BrowserOS MCP gives you a broader automation surface: browser control, content extraction, file operations, and 40+ app integrations through a single connection. Debugging and performance tools are coming soon to BrowserOS MCP, which will close the remaining gap with Chrome DevTools MCP. For most AI agent workflows, BrowserOS MCP already covers more ground out of the box.

docs/comparisons/claude-cowork.mdx

@@ -0,0 +1,161 @@
+---
+title: "Claude Cowork"
+description: "How BrowserOS Cowork compares to Claude Cowork for getting real work done with AI"
+---
+
+Both BrowserOS Cowork and [Claude Cowork](https://claude.com/product/cowork) let an AI agent work with your local files autonomously. You describe a task, step away, and come back to completed work. They share a similar file toolkit under the hood. The key difference is what else each product can do. BrowserOS Cowork runs inside a real browser with full web access and 40+ app integrations. Claude Cowork runs inside an isolated VM with professional document generation.
+
+This page compares both products so you can decide which fits your workflow.
+
+---
+
+## At a Glance
+
+| | **BrowserOS Cowork** | **Claude Cowork** |
+|---|---|---|
+| **Runs in** | Your real browser | Claude Desktop app (VM) |
+| **File tools** | Read, write, edit, search, organize | Read, write, edit, search, organize |
+| **Browser automation** | Yes, 53 tools (click, type, screenshot, navigate, etc.) | No |
+| **App integrations** | 40+ (Gmail, Slack, GitHub, Calendar, Notion, etc.) | ~4 connectors (Google Drive, Gmail, DocuSign) |
+| **AI model** | Your choice (Claude, GPT, Gemini, Kimi, local models) | Claude only |
+| **Internet access** | Full (through your real browser) | Restricted |
+| **Document generation** | Basic (HTML, Markdown, CSV) | Advanced (Excel with formulas, PowerPoint, formatted docs) |
+| **Pricing** | Free (bring your own AI key) | Requires paid Claude subscription |
+| **Platform** | Any OS with BrowserOS | macOS, Windows x64 |
+
+---
+
+## Feature Comparison
+
+### File Operations
+
+Both products provide a comparable set of file tools. You can read, write, edit, search, and organize files in both. This is table-stakes for both products.
+
+| What you can do | BrowserOS Cowork | Claude Cowork |
+|-----------------|:---:|:---:|
+| Read and view files | Yes | Yes |
+| Create and save new files | Yes | Yes |
+| Edit specific parts of a file | Yes | Yes |
+| Search inside files for text | Yes | Yes |
+| Find files by name or pattern | Yes | Yes |
+| List and browse folders | Yes | Yes |
+| Run commands/scripts | Yes | Yes |
+| Break work into parallel subtasks | Coming soon | Built-in sub-agents |
+
+<Note>
+The file tools are largely equivalent. The real differentiator is what else each product can do beyond file operations.
+</Note>
+
+### Working with the Web
+
+This is the biggest difference. BrowserOS Cowork runs inside a real browser with your existing logins and sessions.
+
+| What you can do | BrowserOS Cowork | Claude Cowork |
+|-----------------|:---:|:---:|
+| Open and navigate websites | Yes | No |
+| Click buttons, fill forms, type text | Yes | No |
+| Take screenshots of web pages | Yes | No |
+| Extract content from web pages | Yes | No |
+| Save pages as PDF | Yes | No |
+| Download files from the web | Yes | No |
+| Access sites where you're logged in | Yes (your real browser session) | No |
+| Manage tabs, windows, and bookmarks | Yes | No |
+| Search your browsing history | Yes | No |
+
+Claude Cowork has no browser access. If your task involves anything on the web, whether that's researching, filling out forms, grabbing content from a site, or checking on a web app, you need BrowserOS.
+
+### Connected Apps
+
+BrowserOS connects to 40+ services directly. Claude Cowork has a handful of connectors.
+
+| Service | BrowserOS Cowork | Claude Cowork |
+|---------|:---:|:---:|
+| Gmail | Yes | Yes |
+| Google Drive | Yes | Yes |
+| Google Calendar | Yes | Limited |
+| Slack | Yes | No |
+| GitHub | Yes | No |
+| Linear / Jira / Asana | Yes | No |
+| Notion | Yes | No |
+| Figma | Yes | No |
+| Salesforce / HubSpot | Yes | No |
+| Shopify / Stripe | Yes | No |
+| 30+ more services | Yes | No |
+
+### Document Generation
+
+Claude Cowork has an edge when it comes to creating polished office documents.
+
+| What you can do | BrowserOS Cowork | Claude Cowork |
+|-----------------|:---:|:---:|
+| HTML and Markdown files | Yes | Yes |
+| CSV and data files | Yes | Yes |
+| Excel with working formulas | No | Yes |
+| PowerPoint presentations | No | Yes |
+| Formatted Word documents | No | Yes |
+
+---
+
+## How They Work
+
+<Tabs>
+  <Tab title="BrowserOS Cowork">
+    BrowserOS Cowork runs inside the browser. The agent has access to your real browser session (cookies, logins, extensions) and a sandboxed folder on your computer.
+
+    - Works in your real browser with your existing logins
+    - File access sandboxed to the folder you select
+    - 40+ app integrations via OAuth
+    - Connect from any AI tool (Claude Code, Gemini CLI, Cursor, etc.)
+    - Uses whatever AI model you choose
+  </Tab>
+  <Tab title="Claude Cowork">
+    Claude Cowork runs in an isolated virtual machine on your desktop via the Claude Desktop app.
+
+    - Runs in a secure VM, isolated from your main system
+    - File access to folders you grant permission to
+    - ~4 connectors (Google Drive, Gmail, DocuSign, FactSet)
+    - Only works in the Claude Desktop app
+    - Uses Claude models only
+    - Comes pre-loaded with Python, Node.js, Ruby, and common tools
+  </Tab>
+</Tabs>
+
+---
+
+## Where Claude Cowork Shines
+
+- **Professional documents**: Create Excel spreadsheets with working formulas, PowerPoint presentations, and formatted Word documents
+- **Parallel subtasks**: Automatically breaks complex work into smaller tasks that run at the same time
+- **Stronger isolation**: Runs in a full virtual machine, giving you OS-level separation from your main system
+- **Zero setup**: Works out of the box in the Claude Desktop app with pre-installed tools and languages
+
+---
+
+## Where BrowserOS Cowork Shines
+
+- **Full browser access**: Navigate websites, fill forms, click buttons, take screenshots, and extract content from any page. Claude Cowork cannot touch the web.
+- **Your real logins**: Because it runs in your actual browser, the agent can access sites where you're already logged in: dashboards, internal tools, social media, banking portals, anything.
+- **40+ app integrations**: Gmail, Slack, GitHub, Calendar, Notion, Linear, Figma, Salesforce, and more. All accessible in the same session as your file work. Claude Cowork has about 4 connectors.
+- **Pick your AI model**: Use Claude, GPT-5, Gemini, Kimi K2.5, or a local model. Claude Cowork only works with Claude.
+- **Full internet access**: Your agent can visit any website. Claude Cowork's VM is restricted to a short list of allowed sites.
+- **Free**: BrowserOS is free. Just bring your own AI API key. Claude Cowork requires a paid Claude subscription.
+
+---
+
+## Summary
+
+| | BrowserOS Cowork | Claude Cowork |
+|---|:---:|:---:|
+| File tools (read, write, edit, search) | Yes | Yes |
+| Browse the web | **Yes (53 tools)** | No |
+| Connected apps | **40+** | ~4 |
+| Internet access | Full | Restricted |
+| Choose your AI model | Yes | Claude only |
+| Works with other AI tools | Yes (Claude Code, Gemini CLI, Cursor, etc.) | Claude Desktop only |
+| Excel, PowerPoint, Word | No | **Yes** |
+| Parallel subtasks | Coming soon | **Built-in** |
+| Security model | Folder-level sandbox | VM isolation |
+| Platform | Any OS | macOS, Windows x64 |
+| Pricing | Free + API key | Paid subscription |
+
+Both products handle file operations equally well. The choice comes down to what else you need. If your work touches the web, connected apps, or you want to choose your own AI model, BrowserOS Cowork gives you that. If you need polished office documents and prefer a fully isolated desktop experience, Claude Cowork is a good fit.

docs/comparisons/openclaw.mdx

@@ -0,0 +1,143 @@
+---
+title: "OpenClaw"
+description: "How BrowserOS compares to OpenClaw for everyday AI assistance"
+---
+
+[OpenClaw](https://openclaw.ai/) is an open-source personal AI assistant that runs on your machine and connects through messaging apps like WhatsApp, Telegram, Slack, and Discord. It is a powerful tool for technical users who want a self-hosted, always-on AI agent.
+
+BrowserOS takes a different approach. Instead of running a background server that you message through chat apps, BrowserOS puts the AI assistant directly inside your browser, where most of your work already happens. No terminal setup, no daemon management, no Node.js required.
+
+This comparison is for users deciding which tool fits their needs.
+
+## At a Glance
+
+| | **BrowserOS** | **OpenClaw** |
+|---|---|---|
+| **What it is** | AI-powered browser with built-in assistant | Self-hosted AI agent you message through chat apps |
+| **Setup** | Download and open | Install via npm, run onboarding wizard, configure daemon |
+| **Technical skill needed** | None | Comfortable with terminal and Node.js |
+| **Interface** | Built into your browser | WhatsApp, Telegram, Slack, Discord, iMessage, and 15+ more |
+| **Browser automation** | 53 tools (clicks, forms, navigation, screenshots, tabs, bookmarks, history) | Chrome via CDP (snapshots and actions) |
+| **App integrations** | 40+ built-in (OAuth or API key depending on the service) | Skills-based (community-built, self-installable) |
+| **Memory** | Two-tier: permanent core facts + 30-day daily notes | Persistent memory across conversations |
+| **Personality** | SOUL.md (inspired by OpenClaw's original concept) | SOUL.md (originated the concept) |
+| **LLM support** | 11+ providers including local models (Ollama, LM Studio) | Multiple providers with failover routing |
+| **Runs on** | macOS, Windows, Linux | macOS, Windows, Linux (+ iOS/Android companion apps) |
+| **Authentication** | OAuth or API key depending on the service | API keys, OAuth, pairing codes per channel |
+| **Open source** | Yes (AGPL-3.0) | Yes (MIT) |
+
+## Where BrowserOS Shines
+
+### No technical setup required
+
+OpenClaw requires Node.js 22+, npm installation, a terminal-based onboarding wizard, daemon configuration (launchd or systemd), and channel pairing for each messaging platform. If something goes wrong, you need `openclaw doctor` to diagnose issues.
+
+BrowserOS is a browser. Download it, open it, and start talking to the assistant. There is no daemon to manage, no services to keep running, and no terminal needed.
+
+### Browser automation built in
+
+BrowserOS gives the assistant full control of your browser with 53 tools: clicking buttons, filling forms, navigating between pages, taking screenshots, managing tabs, organizing bookmarks, searching history, and more. The assistant sees what you see and can interact with any website you are logged into.
+
+OpenClaw has browser automation through a dedicated Chrome instance with CDP, but it runs as a separate process rather than being integrated into the browser you are already using. With BrowserOS, the assistant works directly in your browsing session with all your cookies, logins, and open tabs.
+
+### 40+ app integrations built in
+
+BrowserOS connects to Gmail, Google Calendar, Slack, Notion, GitHub, Linear, Jira, Figma, Salesforce, Stripe, and 30+ more services out of the box. Most services connect through OAuth (one-click sign-in), while some require an API key. Either way, the assistant detects when an app is not connected and walks you through the setup right in the conversation.
+
+OpenClaw uses a skills system where integrations are community-built plugins. Some popular services have skills available, but connecting a new service often means finding the right skill, installing it, and configuring credentials manually.
+
+### Works where you already are
+
+Most of your work happens in a browser. BrowserOS puts the assistant right there, so it can see the page you are on, interact with web apps, and pull data from your open tabs. There is no context-switching between a chat app and your browser.
+
+OpenClaw's approach of messaging through WhatsApp or Telegram is clever for mobile use, but when you are at your computer working in a browser, having the assistant inside that browser is more natural and more capable.
+
+## Where OpenClaw Shines
+
+### Messaging app access
+
+OpenClaw connects to 20+ messaging platforms including WhatsApp, Telegram, Signal, iMessage, Discord, Slack, Microsoft Teams, and more. You can message your assistant from your phone or any chat app without opening a specific application. This is ideal if you want AI help on the go through apps you already have open.
+
+BrowserOS is a desktop browser. To use the assistant, you need to be in BrowserOS.
+
+### Always-on background agent
+
+OpenClaw runs as a daemon on your machine, processing tasks even when you are not actively chatting. It supports cron jobs, webhooks, and Gmail Pub/Sub for automated triggers. It can wake up, do something, and report back through your messaging app.
+
+BrowserOS has [scheduled tasks](/features/scheduled-tasks) that run automations on a schedule, but the browser needs to be running. OpenClaw's daemon approach is more suited for server-like always-on operation.
+
+### Mobile companion apps
+
+OpenClaw offers iOS and Android companion apps with camera access, voice input, screen recording, and device-level actions (notifications, contacts, calendar, SMS). This extends the assistant to your phone in a way that BrowserOS cannot currently match.
+
+### Agent-to-agent communication
+
+OpenClaw supports multi-session agent coordination where agents can discover each other, read transcripts, and send messages between sessions. This is useful for complex workflows where multiple specialized agents collaborate.
+
+### Self-modifying skills
+
+OpenClaw agents can write and install their own skills during a conversation. If the assistant does not have a capability, it can create one on the fly. This makes it extremely flexible for power users who want the agent to extend itself.
+
+## Feature Comparison
+
+### App Integrations
+
+| Service | BrowserOS | OpenClaw |
+|---------|-----------|----------|
+| Gmail | Built-in (OAuth) | Skill + API setup |
+| Google Calendar | Built-in (OAuth) | Skill + API setup |
+| Slack | Built-in (OAuth) | Built-in channel |
+| Discord | Built-in (OAuth) | Built-in channel |
+| Notion | Built-in (OAuth) | Skill |
+| GitHub | Built-in (OAuth) | Skill |
+| Linear | Built-in (OAuth or API key) | Skill |
+| Jira | Built-in (OAuth) | Skill |
+| Figma | Built-in (OAuth) | Skill |
+| Salesforce | Built-in (OAuth) | Skill |
+| Stripe | Built-in (API key) | Skill |
+| WhatsApp | Built-in (OAuth) | Built-in channel |
+| Shopify | Built-in (OAuth or API key) | Community skill |
+| Total integrations | 40+ built-in | 50+ via skills |
+
+### Memory and Personality
+
+| Feature | BrowserOS | OpenClaw |
+|---------|-----------|----------|
+| Persistent memory | Core facts (permanent) + daily notes (30 days) | Persistent across sessions |
+| Memory location | Local files on your machine | Local files on your machine |
+| Personality system | SOUL.md (inspired by OpenClaw) | SOUL.md (originated the concept) |
+| Memory search | Fuzzy search across all memories | Context-based recall |
+
+### Setup and Maintenance
+
+| | BrowserOS | OpenClaw |
+|---|-----------|----------|
+| Installation | Download browser | `npm install -g openclaw`, run onboarding wizard |
+| Runtime | Open the browser | Daemon process (launchd/systemd) |
+| Updates | Auto-update | `openclaw update --channel stable` |
+| Troubleshooting | Built-in | `openclaw doctor` CLI tool |
+| Node.js required | No | Yes (v22+) |
+| Terminal required | No | Yes |
+
+## Who Should Use What
+
+<CardGroup cols={2}>
+  <Card title="Choose BrowserOS if you..." icon="browser">
+    - Want an AI assistant without any technical setup
+    - Do most of your work in a browser
+    - Need browser automation (filling forms, clicking buttons, extracting data)
+    - Want 40+ app integrations that connect with one click
+    - Prefer a visual interface over terminal commands
+  </Card>
+  <Card title="Choose OpenClaw if you..." icon="terminal">
+    - Want to message your AI from WhatsApp, Telegram, or Signal
+    - Need an always-on agent that runs 24/7 as a background service
+    - Are comfortable with Node.js and terminal-based setup
+    - Want mobile companion apps for on-the-go access
+    - Need agents that can write their own extensions
+  </Card>
+</CardGroup>
+
+## Using Both Together
+
+BrowserOS and OpenClaw are not mutually exclusive. Some users run OpenClaw as their always-on mobile assistant (accessible through WhatsApp or Telegram) while using BrowserOS as their desktop browser for work that involves web apps, browser automation, and visual tasks. The two tools complement each other rather than compete directly.

docs/contributing.mdx

@@ -1,530 +1,267 @@
 ---
 title: "Contributing to BrowserOS"
-description: "Let's build the best open-source browser!"
-icon: "code-branch"
+description: "Guide to contributing to BrowserOS"
 ---
 
-Hey there! Thanks for your interest in BrowserOS. Whether you're fixing bugs, adding features, improving docs, or just poking around the code, we're glad you're here.
+BrowserOS has two main parts you can contribute to:
 
-BrowserOS is a monorepo with two main parts:
-- **Agent** - The Chrome extension with AI features (TypeScript/React)
-- **Browser** - The custom Chromium build (C++/Python)
+- **Agent** — The AI features, UI, and browser automation (TypeScript/React)
+- **Browser** — The custom Chromium build (C++/Python)
 
-Most folks start with the agent since it's way easier to set up and iterate on.
+Most contributors work on the Agent since it's much easier to set up.
 
-## 1. Quick Links
+## Quick Links
 
-<CardGroup cols={3}>
-  <Card
-    title="GitHub Repository"
-    icon="github"
-    href="https://github.com/BrowserOS-ai/BrowserOS"
-  >
-    Star, fork, and contribute to our codebase
-  </Card>
-  <Card
-    title="Discord Community"
-    icon="discord"
-    href="https://discord.gg/YKwjt5vuKr"
-  >
-    Join our community for discussions and support
-  </Card>
-  <Card
-    title="Report Issues"
-    icon="bug"
-    href="https://github.com/BrowserOS-ai/BrowserOS/issues"
-  >
-    Report bugs or suggest new features
-  </Card>
-</CardGroup>
+- [GitHub Repository](https://github.com/BrowserOS-ai/BrowserOS)
+- [Discord Community](https://discord.gg/YKwjt5vuKr)
+- [Report Issues](https://github.com/BrowserOS-ai/BrowserOS/issues)
 
-## 2. Ways to Contribute
+## Ways to Contribute
 
-You can contribute to BrowserOS in many ways! Whether you want to build features or help out in other ways, we appreciate all contributions.
+**Report bugs** — [Open an issue](https://github.com/browseros-ai/BrowserOS/issues/new) with steps to reproduce, expected vs actual behavior, and screenshots.
 
-<Tabs>
-  <Tab title="🐛 Report Bugs">
-    Found a bug? [Open an issue](https://github.com/browseros-ai/BrowserOS/issues/new) with:
-    - Clear description
-    - Steps to reproduce
-    - Expected vs actual behavior
-    - Screenshots/videos
-    - Environment details (OS, browser version, BrowserOS version)
-  </Tab>
+**Suggest features** — Share ideas on [GitHub](https://github.com/browseros-ai/BrowserOS/issues/99) or [Discord](https://discord.gg/YKwjt5vuKr).
 
-  <Tab title="💡 Suggest Features">
-    Have an idea? [Share it here](https://github.com/browseros-ai/BrowserOS/issues/99) or chat with us on [Discord](https://discord.gg/YKwjt5vuKr).
-  </Tab>
+**Improve docs** — Docs live in `docs/` and use Mintlify. Edit pages and update `docs/docs.json` for navigation.
 
-  <Tab title="📚 Improve Docs">
-    We use <b>Mintlify</b> for our documentation. All docs live in the <code>docs/</code> directory.
+---
 
-    - Add new documentation pages or update existing ones under <code>docs/</code>
-    - Help clarify instructions; add examples, tutorials, or guides
-    - After adding or editing a page, update <code>docs/docs.json</code> to include your new or changed file in the navigation
+## Path 1: Agent Development
 
-    If you have questions about the docs system, ask in Discord!
-  </Tab>
-</Tabs>
+The Agent is a monorepo with 3 components:
 
-## 3. Pick Your Path
+| Component | Path | What it does |
+|-----------|------|--------------|
+| **Agent UI** | `apps/agent` | Chrome extension — chat interface, settings, side panel |
+| **Server** | `apps/server` | Bun server — agent loop, MCP tools, API endpoints |
+| **Controller** | `apps/controller-ext` | Chrome extension — bridges `chrome.*` APIs to the server |
 
-If you want to contribute to development, here are two paths you can take:
+### Architecture
 
-<CardGroup cols={2}>
-  <Card title="Agent Development" icon="robot">
-    **What you'll work on:**
-    - AI agent features & tools
-    - UI/UX improvements
-    - Browser automation
-    - Testing & docs
+<img src="/images/contributing--architecture.png" alt="BrowserOS Agent architecture diagram" />
 
-    **What you need:**
-    - Node.js 18+
-    - ~500MB disk space
-    - 10 minutes to set up
+### Setup
 
-    **Skills:** TypeScript, React, Chrome APIs
-  </Card>
-  <Card title="Browser Development" icon="globe">
-    **What you'll work on:**
-    - Chromium patches
-    - Build system
-    - Platform features
-    - Core browser stuff
+```bash
+# Clone the repo
+git clone https://github.com/YOUR-USERNAME/BrowserOS.git
+cd BrowserOS/packages/browseros-agent
 
-    **What you need:**
-    - ~100GB disk space
-    - 16GB+ RAM (recommended)
-    - 3+ hours for first build
+# Install dependencies
+bun install
 
-    **Skills:** C++, Python, Chromium internals
-  </Card>
-</CardGroup>
+# Copy environment files
+cp apps/server/.env.example apps/server/.env.development
+cp apps/agent/.env.example apps/agent/.env.development
+```
 
-### 3.1 Agent Development
+### Running Locally
 
-The agent is a Chrome extension that provides AI-powered automation. Most contributors work here.
+```bash
+# Terminal 1: Start the server
+bun run start:server
 
-<Accordion title="Instructions">
+# Terminal 2: Start the agent extension (dev mode)
+bun run start:agent
+```
 
-#### Quick Setup
+Then load the extension in BrowserOS:
+1. Go to `chrome://extensions/`
+2. Enable **Developer mode**
+3. Click **Load unpacked** and select the `apps/agent/dist/` folder
 
-<Steps>
-  <Step title="Navigate to Agent Directory">
-    ```bash
-    cd packages/browseros-agent
-    ```
-  </Step>
+### Commands
 
-  <Step title="Install Dependencies">
-    ```bash
-    yarn install
-    ```
-  </Step>
+| Command | Description |
+|---------|-------------|
+| `bun run start:server` | Start the server |
+| `bun run start:agent` | Start agent extension (dev mode) |
+| `bun run build:server` | Build server for production |
+| `bun run build:agent` | Build agent extension |
+| `bun run build:ext` | Build controller extension |
+| `bun run test` | Run tests |
+| `bun run lint` | Check with Biome |
+| `bun run typecheck` | TypeScript check |
 
-  <Step title="Set Up Environment">
-    ```bash
-    cp .env.example .env
-    ```
-    Edit `.env` and add your `LITELLM_API_KEY`
-  </Step>
+---
 
-  <Step title="Build the Extension">
-    ```bash
-    yarn build:dev       # One-time build
-    ```
-  </Step>
-</Steps>
+## Path 2: Browser Development
 
-#### Load in BrowserOS
+Only go down this path if you're working on Chromium-level features like patches to the browser itself.
 
-<Steps>
-  <Step title="Open Extensions Page">
-    Navigate to `chrome://extensions/`
-  </Step>
+**Requirements:**
+- ~100GB disk space
+- 16GB+ RAM recommended
+- 3+ hours for first build
 
-  <Step title="Enable Developer Mode">
-    Toggle **Developer mode** in the top right
-  </Step>
-
-  <Step title="Load Unpacked Extension">
-    Click **Load unpacked** and select `packages/browseros-agent/dist/`
-  </Step>
-
-  <Step title="Open Agent Panel">
-    Press the Agent icon from the extensions toolbar to open the agent panel
-  </Step>
-</Steps>
-
-<Note>
-For detailed setup, architecture, and code standards, see the [Agent Contributing Guide](https://github.com/BrowserOS-ai/BrowserOS/blob/main/packages/browseros-agent/CONTRIBUTING.md).
-</Note>
-
-</Accordion>
-
-### 3.2 Browser Development
-
-Building the custom Chromium browser requires significant disk space and time. Only go down this path if you're working on browser-level features like patches to Chromium itself.
-
-<Accordion title="Instructions">
-
-#### Prerequisites
+### Prerequisites
 
 <Tabs>
   <Tab title="macOS">
-    - macOS (tested on M4 Max)
-    - Xcode and Command Line Tools
+    - macOS with Xcode and Command Line Tools
     - Python 3.12+
     - [UV](https://docs.astral.sh/uv/) (Python package manager)
     - Git
-    - ~100GB of free disk space (for Chromium source)
-    - ~16GB RAM (recommended)
   </Tab>
   <Tab title="Linux">
     - Ubuntu 20.04+ or similar
     - build-essential package
     - Python 3.12+
-    - [UV](https://docs.astral.sh/uv/) (Python package manager)
+    - [UV](https://docs.astral.sh/uv/)
     - Git
-    - ~100GB of free disk space
-    - ~16GB RAM (recommended)
   </Tab>
   <Tab title="Windows">
     - Windows 10/11
     - Visual Studio 2022 with C++ workload
     - Python 3.12+
-    - [UV](https://docs.astral.sh/uv/) (Python package manager)
+    - [UV](https://docs.astral.sh/uv/)
     - Git
-    - ~100GB of free disk space
-    - ~16GB RAM minimum
   </Tab>
 </Tabs>
 
-#### Build Instructions
+### Build Instructions
 
-<Steps>
-  <Step title="Clone Chromium Source">
-    Follow the official Chromium guide for your platform to clone the source code:
+**1. Clone Chromium source**
 
-    **[Chromium: Get the Code](https://www.chromium.org/developers/how-tos/get-the-code/)**
+Follow the official [Chromium: Get the Code](https://www.chromium.org/developers/how-tos/get-the-code/) guide. This sets up `depot_tools` and fetches ~100GB of source code.
 
-    This sets up `depot_tools` and fetches the Chromium source tree (~100GB).
+Note the path where you clone it (e.g., `~/chromium/src`).
 
-    <Info>
-    Take note of the path where you clone Chromium (e.g., `~/chromium/src`). You'll need this path for the build commands.
-    </Info>
-  </Step>
+**2. Install UV and dependencies**
 
-  <Step title="Install UV and Dependencies">
-    Install UV if you haven't already, then install the build system dependencies:
+```bash
+# Install UV
+curl -LsSf https://astral.sh/uv/install.sh | sh
 
+# Navigate to build system
+cd packages/browseros
+
+# Install dependencies
+uv sync
+```
+
+**3. Build debug version**
+
+```bash
+uv run browseros build \
+  --chromium-src <your-chromium-src-path> \
+  --setup \
+  --prep \
+  --build \
+  --build-type debug
+```
+
+The `--setup` and `--prep` flags are only needed for the first build. After that, just use `--build` for incremental builds:
+
+```bash
+uv run browseros build --chromium-src <path> --build --build-type debug
+```
+
+**4. Run BrowserOS**
+
+<Tabs>
+  <Tab title="macOS (ARM64)">
     ```bash
-    # Install UV (if not installed)
-    curl -LsSf https://astral.sh/uv/install.sh | sh
-
-    # Navigate to the build system directory
-    cd packages/browseros
-
-    # Install all dependencies
-    uv sync
+    <chromium-src>/out/Default_arm64/BrowserOS\ Dev.app/Contents/MacOS/BrowserOS\ Dev \
+      --enable-logging=stderr \
+      --use-mock-keychain \
+      --user-data-dir=/tmp/test-profile
     ```
-  </Step>
-
-  <Step title="Build Debug Version">
-    Run the build command with your Chromium source path:
-
+  </Tab>
+  <Tab title="macOS (x64)">
     ```bash
-    uv run browseros build \
-      --chromium-src <your-chromium-src-path> \
-      --setup \
-      --prep \
-      --build \
-      --build-type debug
+    <chromium-src>/out/Default_x64/BrowserOS\ Dev.app/Contents/MacOS/BrowserOS\ Dev \
+      --enable-logging=stderr \
+      --use-mock-keychain \
+      --user-data-dir=/tmp/test-profile
     ```
-
-    Replace `<your-chromium-src-path>` with the actual path to your Chromium source directory (e.g., `~/chromium/src`).
-
-    <Info>
-    The `--setup` and `--prep` flags are only needed for the first build. After that, you can just use `--build` for incremental builds.
-    </Info>
-  </Step>
-
-  <Step title="Build Release Version (Optional)">
-    For a production-optimized build:
-
+  </Tab>
+  <Tab title="Windows">
     ```bash
-    uv run browseros build \
-      --chromium-src <your-chromium-src-path> \
-      --setup \
-      --prep \
-      --build \
-      --build-type release
+    <chromium-src>\out\Default_x64\BrowserOS Dev.exe \
+      --enable-logging=stderr \
+      --user-data-dir=%TEMP%\test-profile
     ```
+  </Tab>
+  <Tab title="Linux">
+    ```bash
+    <chromium-src>/out/Default_x64/browseros \
+      --enable-logging=stderr \
+      --user-data-dir=/tmp/test-profile
+    ```
+  </Tab>
+</Tabs>
 
-    <Warning>
-    Release builds take longer to compile but produce faster, smaller binaries.
-    </Warning>
-  </Step>
-
-  <Step title="Run BrowserOS">
-    After the build completes, you'll find BrowserOS Dev in the output directory.
-
-    <Tabs>
-      <Tab title="macOS (ARM64)">
-        ```bash
-        <your-chromium-src-path>/out/Default_arm64/BrowserOS\ Dev.app/Contents/MacOS/BrowserOS\ Dev \
-          --enable-logging=stderr \
-          --use-mock-keychain \
-          --user-data-dir=/tmp/test-profile
-        ```
-      </Tab>
-      <Tab title="macOS (x64)">
-        ```bash
-        <your-chromium-src-path>/out/Default_x64/BrowserOS\ Dev.app/Contents/MacOS/BrowserOS\ Dev \
-          --enable-logging=stderr \
-          --use-mock-keychain \
-          --user-data-dir=/tmp/test-profile
-        ```
-      </Tab>
-      <Tab title="Windows">
-        ```bash
-        <your-chromium-src-path>\out\Default_x64\BrowserOS Dev.exe \
-          --enable-logging=stderr \
-          --user-data-dir=%TEMP%\test-profile
-        ```
-      </Tab>
-      <Tab title="Linux">
-        ```bash
-        <your-chromium-src-path>/out/Default_x64/browseros \
-          --enable-logging=stderr \
-          --user-data-dir=/tmp/test-profile
-        ```
-      </Tab>
-    </Tabs>
-
-    <Tip>
-    The `--user-data-dir` flag creates an isolated profile, keeping your development browser separate from any existing profiles.
-    </Tip>
-  </Step>
-</Steps>
-
-#### Build Flags Reference
+### Build Flags
 
 | Flag | Description |
 |------|-------------|
-| `--chromium-src` | Path to your Chromium source directory (required) |
-| `--setup` | Run setup phase (clean, git setup) |
-| `--prep` | Run prep phase (resources, patches, configure) |
+| `--chromium-src` | Path to Chromium source directory |
+| `--setup` | Run setup phase (first build only) |
+| `--prep` | Run prep phase (first build only) |
 | `--build` | Run the compile phase |
-| `--build-type` | Build type: `debug` or `release` |
-| `--sign` | Sign the build (platform-specific) |
+| `--build-type` | `debug` or `release` |
+| `--sign` | Sign the build |
 | `--package` | Package for distribution |
 
-<Tip>
-For incremental builds after your first build, you only need `--build`:
-```bash
-uv run browseros build --chromium-src <your-chromium-src-path> --build --build-type debug
-```
-</Tip>
+### Troubleshooting
 
-#### Troubleshooting
+**Build fails with missing dependencies** — Make sure you followed all steps from the Chromium build guide for your platform.
 
-<Accordion title="Build fails with missing dependencies">
-  - Make sure you've followed all prerequisite steps from the Chromium build guide
-  - Ensure Xcode is up to date (macOS)
-  - Verify all required packages are installed (Linux)
-  - Check Visual Studio installation (Windows)
-</Accordion>
+**Out of disk space** — Chromium needs ~100GB. Check with `df -h`.
 
-<Accordion title="Out of disk space">
-  Chromium requires significant disk space (~100GB). Ensure you have enough free space before starting the build. You can use `df -h` on Unix systems or check Disk Management on Windows.
-</Accordion>
+**Build takes too long** — Use ccache, more CPU cores, or stick to debug builds.
 
-<Accordion title="Build takes too long">
-  - Use ccache to speed up rebuilds
-  - Consider using a machine with more CPU cores
-  - Build only the components you need for development
-  - Use debug builds for faster compilation times
-</Accordion>
-
-<Accordion title="UV command not found">
-  Make sure UV is installed and in your PATH:
-  ```bash
-  curl -LsSf https://astral.sh/uv/install.sh | sh
-  source ~/.bashrc  # or restart your terminal
-  ```
-</Accordion>
-
-</Accordion>
-
-## 4. Making Your First Contribution
-
-Open a PR on GitHub with:
-- **Clear title** in conventional commit format
-- **Description** explaining what changed and why
-- **Screenshots/videos** for UI changes
-- **Link to related issues** (e.g., "Fixes #123")
-
-### Sign the CLA
-
-On your first PR, our bot will ask you to sign the Contributor License Agreement:
-
-<Steps>
-  <Step title="Read the CLA">
-    Read the [CLA document](https://github.com/BrowserOS-ai/BrowserOS/blob/main/CLA.md)
-  </Step>
-
-  <Step title="Sign via Comment">
-    Comment on your PR:
-    ```
-    I have read the CLA Document and I hereby sign the CLA
-    ```
-  </Step>
-
-  <Step title="Automatic Recording">
-    The bot will record your signature (one-time thing)
-  </Step>
-</Steps>
-
-## 5. Code Standards
-
-### TypeScript (Agent)
-
-- **Strict typing** - Always declare types, avoid `any`
-- **Zod schemas** - Use Zod instead of TypeScript interfaces
-- **Path aliases** - Use `@/lib` not relative paths like `../`
-- **Naming:**
-  - Classes: `PascalCase`
-  - Functions/variables: `camelCase`
-  - Constants: `UPPERCASE`
-  - Private methods: prefix with `_`
-
-**Example:**
-
-```typescript
-import { z } from 'zod'
-
-// Good: Zod schema with inline comments
-export const ToolInputSchema = z.object({
-  action: z.enum(['click', 'type']),  // Action to perform
-  target: z.string().min(1),  // Element selector
-  timeout: z.number().default(5000)  // Timeout in ms
-})
-
-export type ToolInput = z.infer<typeof ToolInputSchema>
-```
-
-### React (Agent UI)
-
-- **Styling:** Tailwind CSS only (no SCSS or CSS modules)
-- **Hooks:** Only at top level
-- **Props:** Define with Zod schemas
-- **Testing:** Vitest (not Jest)
-
-### General Guidelines
-
-- Keep functions short (\<20 lines ideally)
-- Write tests for new features
-- Use descriptive variable names
-- Handle errors gracefully
-
-<Note>
-claude.md file can be found at below:
-- Agent: [packages/browseros-agent/CLAUDE.md](https://github.com/BrowserOS-ai/BrowserOS/blob/main/packages/browseros-agent/CLAUDE.md)
-</Note>
-
-## 6. Project Structure
-
-```
-monorepo/
-├── packages/
-│   ├── browseros/              # Chromium build system
-│   │   ├── build/             # Python build scripts
-│   │   ├── chromium_patches/  # Patches to Chromium source
-│   │   └── resources/         # Icons, configs
-│   │
-│   └── browseros-agent/        # Chrome extension
-│       ├── src/
-│       │   ├── lib/           # Core agent logic
-│       │   ├── sidepanel/     # Side panel UI
-│       │   ├── newtab/        # New tab page
-│       │   └── background/    # Extension background
-│       └── docs/              # Architecture docs
-│
-├── docs/                       # General documentation
-└── CONTRIBUTING.md            # Contributing guide
-```
-
-## 7. Development Workflow
-
-<Steps>
-  <Step title="Fork and Clone">
-    Fork the repository on GitHub and clone it locally:
-    ```bash
-    git clone https://github.com/YOUR-USERNAME/BrowserOS.git
-    cd BrowserOS
-    ```
-  </Step>
-
-  <Step title="Create a Branch">
-    Create a new branch for your feature or fix:
-    ```bash
-    git checkout -b feature/your-feature-name
-    ```
-  </Step>
-
-  <Step title="Make Changes">
-    Make your changes and test them thoroughly. Follow our coding standards and ensure all tests pass.
-  </Step>
-
-  <Step title="Commit and Push">
-    Commit your changes with a descriptive message:
-    ```bash
-    git add .
-    git commit -m "feat: add new feature description"
-    git push origin feature/your-feature-name
-    ```
-  </Step>
-
-  <Step title="Submit PR">
-    Open a pull request on GitHub with a clear description of your changes and why they're needed.
-  </Step>
-</Steps>
-
-## 8. Support
-
-Stuck? Need clarification? We're here to help.
-
-<CardGroup cols={3}>
-  <Card
-    title="Discord Support"
-    icon="discord"
-    href="https://discord.gg/YKwjt5vuKr"
-  >
-    Real-time chat and support
-  </Card>
-  <Card
-    title="GitHub Issues"
-    icon="bug"
-    href="https://github.com/browseros-ai/BrowserOS/issues"
-  >
-    Bug reports and features
-  </Card>
-  <Card
-    title="GitHub Discussions"
-    icon="comments"
-    href="https://github.com/browseros-ai/BrowserOS/discussions"
-  >
-    General questions
-  </Card>
-</CardGroup>
-
-
-## 9. License
-
-By contributing, you agree that your contributions will be licensed under AGPL-3.0.
+**UV command not found** — Restart your terminal after installing UV.
 
 ---
 
-Built with ❤️ from San Francisco
+## Making Your First PR
+
+1. **Fork** the repository on GitHub
+2. **Clone** your fork locally
+3. **Create a branch**: `git checkout -b feature/your-feature`
+4. **Make changes** and test them
+5. **Commit**: `git commit -m "feat: add your feature"`
+6. **Push**: `git push origin feature/your-feature`
+7. **Open a PR** with a clear description
+
+### Sign the CLA
+
+On your first PR, our bot will ask you to sign the Contributor License Agreement. Just comment:
+
+```
+I have read the CLA Document and I hereby sign the CLA
+```
+
+---
+
+## Code Standards
+
+**TypeScript:**
+- Use strict typing, avoid `any`
+- Use Zod schemas instead of TypeScript interfaces
+- Use path aliases (`@/lib`) not relative paths (`../`)
+- Naming: `PascalCase` for classes, `camelCase` for functions
+
+**React:**
+- Tailwind CSS only (no SCSS or CSS modules)
+- Hooks at top level only
+- Test with Vitest
+
+**General:**
+- Keep functions short (under 20 lines)
+- Write tests for new features
+- Handle errors gracefully
+
+---
+
+## Getting Help
+
+- **Discord** — [discord.gg/YKwjt5vuKr](https://discord.gg/YKwjt5vuKr)
+- **GitHub Issues** — [github.com/BrowserOS-ai/BrowserOS/issues](https://github.com/BrowserOS-ai/BrowserOS/issues)
+- **GitHub Discussions** — [github.com/BrowserOS-ai/BrowserOS/discussions](https://github.com/BrowserOS-ai/BrowserOS/discussions)
+
+---
+
+By contributing, you agree that your contributions will be licensed under AGPL-3.0.

docs/docs.json

@@ -15,45 +15,52 @@
         "pages": [
           "index",
           "onboarding",
-          "update"
-        ]
-      },
-      {
-        "group": "Bring Your Own LLM",
-        "pages": [
-          "llm-setup-guide",
-          {
-            "group": "Cloud Providers",
-            "pages": [
-              "bring-your-own-keys/gemini",
-              "bring-your-own-keys/claude",
-              "bring-your-own-keys/openai",
-              "bring-your-own-keys/openrouter"
-            ]
-          },
-          {
-            "group": "Local LLMs",
-            "pages": [
-              "local-LLMs/ollama",
-              "local-LLMs/lm-studio",
-              "local-LLMs/gpt-oss"
-            ]
-          }
+          "update/index",
+          "changelog"
         ]
       },
       {
         "group": "Core Features",
         "pages": [
+          "features/bring-your-own-llm",
+          "features/chatgpt-pro-oauth",
+          "features/github-copilot-oauth",
+          "features/qwen-code-oauth",
+          "features/local-models",
+          "features/workflows",
+          "features/scheduled-tasks",
+          "features/cowork",
+          "features/connect-mcps",
+          "features/skills",
+          "features/smart-nudges",
+          "features/use-with-claude-code",
+          "features/soul",
+          "features/memory",
+          "features/sync-to-cloud",
+          "features/llm-chat-hub",
           "features/ad-blocking",
-          "browseros-mcp/how-to-guide",
-          "integrations/n8n"
+          "features/vertical-tabs"
         ]
       },
       {
-        "group": "Contributing",
+        "group": "Comparisons",
         "pages": [
-          "contributing"
+          "comparisons/chrome-devtools-mcp",
+          "comparisons/claude-cowork",
+          "comparisons/openclaw"
         ]
+      },
+      {
+        "group": "Integrations",
+        "pages": ["integrations/n8n"]
+      },
+      {
+        "group": "Troubleshooting",
+        "pages": ["troubleshooting/connection-issues"]
+      },
+      {
+        "group": "Contributing",
+        "pages": ["contributing"]
       }
     ]
   },
@@ -63,6 +70,10 @@
   },
   "navbar": {
     "links": [
+      {
+        "label": "llms.txt",
+        "href": "/llms.txt"
+      },
       {
         "label": "Support",
         "href": "https://discord.gg/YKwjt5vuKr"

docs/features/ad-blocking.mdx

@@ -1,15 +1,19 @@
 ---
 title: "Ad Blocking"
-description: "BrowserOS blocks 10x more ads than Chrome out of the box"
+description: "BrowserOS supports full ad blocking with uBlock Origin"
 ---
 
-BrowserOS ships with built-in ad blocking that works immediately—no extensions required.
+BrowserOS supports full ad blocking through [uBlock Origin](https://ublockorigin.com/), the most powerful open-source ad blocker available — the full extension, not the watered-down "Lite" version.
 
-## How It Works
+## Why BrowserOS?
 
-BrowserOS comes pre-installed with [uBlock Origin](https://ublockorigin.com/), the most effective open-source ad blocker available. Chrome has been [phasing out support](https://developer.chrome.com/docs/extensions/develop/migrate/mv2-deprecation-timeline) for Manifest V2 extensions, which uBlock Origin relies on for its full blocking capabilities.
+Chrome [killed support](https://developer.chrome.com/docs/extensions/develop/migrate/mv2-deprecation-timeline) for uBlock Origin by phasing out Manifest V2 extensions. The only option left on Chrome is "uBlock Origin Lite," a significantly weaker version that can't use advanced filtering rules.
 
-We re-enabled Manifest V2 support in BrowserOS to keep uBlock Origin running at full power. You get the same [uBlock Origin from the Chrome Web Store](https://chrome.google.com/webstore/detail/ublock-origin/cjpalhdlnbpafiamejdnhcphjbkeiagm)—we just make sure it actually works.
+**BrowserOS re-enabled full Manifest V2 support**, so you can install and run the original uBlock Origin at full power — the same extension Chrome no longer allows.
+
+<Card title="Install uBlock Origin" icon="shield-check" href="https://chromewebstore.google.com/detail/ublock-origin/cjpalhdlnbpafiamejdnhcphjbkeiagm">
+  Install the full uBlock Origin extension from the Chrome Web Store. Works on BrowserOS out of the box.
+</Card>
 
 ## BrowserOS vs Chrome
 

docs/features/bring-your-own-llm.mdx

@@ -0,0 +1,284 @@
+---
+title: "Bring Your Own LLM"
+description: "Connect your own AI models to BrowserOS"
+---
+
+BrowserOS includes a default AI model you can use right away, but it has strict rate limits. For the best experience, bring your own API keys or run models locally.
+
+See how to connect your own LLM in under a minute:
+
+<video
+  controls
+  className="w-full aspect-video rounded-xl"
+  src="https://pub-80f8a01e6e8b4239ae53a7652ef85877.r2.dev/resources/feature-videos/1-bring-your-own-LLM.mov"
+></video>
+
+## Use Your Existing Subscription
+
+Already paying for ChatGPT Pro, GitHub Copilot, or Qwen Code? Connect your existing account to BrowserOS with a single sign-in — no API keys, no extra cost.
+
+<CardGroup cols={3}>
+  <Card href="/features/chatgpt-pro-oauth">
+    <svg fill="currentColor" fillRule="evenodd" height="24" width="24" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"><path d="M9.205 8.658v-2.26c0-.19.072-.333.238-.428l4.543-2.616c.619-.357 1.356-.523 2.117-.523 2.854 0 4.662 2.212 4.662 4.566 0 .167 0 .357-.024.547l-4.71-2.759a.797.797 0 00-.856 0l-5.97 3.473zm10.609 8.8V12.06c0-.333-.143-.57-.429-.737l-5.97-3.473 1.95-1.118a.433.433 0 01.476 0l4.543 2.617c1.309.76 2.189 2.378 2.189 3.948 0 1.808-1.07 3.473-2.76 4.163zM7.802 12.703l-1.95-1.142c-.167-.095-.239-.238-.239-.428V5.899c0-2.545 1.95-4.472 4.591-4.472 1 0 1.927.333 2.712.928L8.23 5.067c-.285.166-.428.404-.428.737v6.898zM12 15.128l-2.795-1.57v-3.33L12 8.658l2.795 1.57v3.33L12 15.128zm1.796 7.23c-1 0-1.927-.332-2.712-.927l4.686-2.712c.285-.166.428-.404.428-.737v-6.898l1.974 1.142c.167.095.238.238.238.428v5.233c0 2.545-1.974 4.472-4.614 4.472zm-5.637-5.303l-4.544-2.617c-1.308-.761-2.188-2.378-2.188-3.948A4.482 4.482 0 014.21 6.327v5.423c0 .333.143.571.428.738l5.947 3.449-1.95 1.118a.432.432 0 01-.476 0zm-.262 3.9c-2.688 0-4.662-2.021-4.662-4.519 0-.19.024-.38.047-.57l4.686 2.71c.286.167.571.167.856 0l5.97-3.448v2.26c0 .19-.07.333-.237.428l-4.543 2.616c-.619.357-1.356.523-2.117.523zm5.899 2.83a5.947 5.947 0 005.827-4.756C22.287 18.339 24 15.84 24 13.296c0-1.665-.713-3.282-1.998-4.448.119-.5.19-.999.19-1.498 0-3.401-2.759-5.947-5.946-5.947-.642 0-1.26.095-1.88.31A5.962 5.962 0 0010.205 0a5.947 5.947 0 00-5.827 4.757C1.713 5.447 0 7.945 0 10.49c0 1.666.713 3.283 1.998 4.448-.119.5-.19 1-.19 1.499 0 3.401 2.759 5.946 5.946 5.946.642 0 1.26-.095 1.88-.309a5.96 5.96 0 004.162 1.713z"></path></svg>
+    **ChatGPT Pro / Plus**
+
+    Sign in with your OpenAI account. Access GPT-5 Codex, GPT-5.4, and the full Codex lineup with up to 400K context.
+  </Card>
+  <Card href="/features/github-copilot-oauth">
+    <svg fill="currentColor" fillRule="evenodd" height="24" width="24" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"><path d="M19.245 5.364c1.322 1.36 1.877 3.216 2.11 5.817.622 0 1.2.135 1.592.654l.73.964c.21.278.323.61.323.955v2.62c0 .339-.173.669-.453.868C20.239 19.602 16.157 21.5 12 21.5c-4.6 0-9.205-2.583-11.547-4.258-.28-.2-.452-.53-.453-.868v-2.62c0-.345.113-.679.321-.956l.73-.963c.392-.517.974-.654 1.593-.654l.029-.297c.25-2.446.81-4.213 2.082-5.52 2.461-2.54 5.71-2.851 7.146-2.864h.198c1.436.013 4.685.323 7.146 2.864zm-7.244 4.328c-.284 0-.613.016-.962.05-.123.447-.305.85-.57 1.108-1.05 1.023-2.316 1.18-2.994 1.18-.638 0-1.306-.13-1.851-.464-.516.165-1.012.403-1.044.996a65.882 65.882 0 00-.063 2.884l-.002.48c-.002.563-.005 1.126-.013 1.69.002.326.204.63.51.765 2.482 1.102 4.83 1.657 6.99 1.657 2.156 0 4.504-.555 6.985-1.657a.854.854 0 00.51-.766c.03-1.682.006-3.372-.076-5.053-.031-.596-.528-.83-1.046-.996-.546.333-1.212.464-1.85.464-.677 0-1.942-.157-2.993-1.18-.266-.258-.447-.661-.57-1.108-.32-.032-.64-.049-.96-.05zm-2.525 4.013c.539 0 .976.426.976.95v1.753c0 .525-.437.95-.976.95a.964.964 0 01-.976-.95v-1.752c0-.525.437-.951.976-.951zm5 0c.539 0 .976.426.976.95v1.753c0 .525-.437.95-.976.95a.964.964 0 01-.976-.95v-1.752c0-.525.437-.951.976-.951zM7.635 5.087c-1.05.102-1.935.438-2.385.906-.975 1.037-.765 3.668-.21 4.224.405.394 1.17.657 1.995.657h.09c.649-.013 1.785-.176 2.73-1.11.435-.41.705-1.433.675-2.47-.03-.834-.27-1.52-.63-1.813-.39-.336-1.275-.482-2.265-.394zm6.465.394c-.36.292-.6.98-.63 1.813-.03 1.037.24 2.06.675 2.47.968.957 2.136 1.104 2.776 1.11h.044c.825 0 1.59-.263 1.995-.657.555-.556.765-3.187-.21-4.224-.45-.468-1.335-.804-2.385-.906-.99-.088-1.875.058-2.265.394zM12 7.615c-.24 0-.525.015-.84.044.03.16.045.336.06.526l-.001.159a2.94 2.94 0 01-.014.25c.225-.022.425-.027.612-.028h.366c.187 0 .387.006.612.028-.015-.146-.015-.277-.015-.409.015-.19.03-.365.06-.526a9.29 9.29 0 00-.84-.044z"></path></svg>
+    **GitHub Copilot**
+
+    Sign in with your GitHub account. Access 19+ models including Claude, GPT-5, and Gemini through one subscription.
+  </Card>
+  <Card href="/features/qwen-code-oauth">
+    <svg fill="currentColor" fillRule="evenodd" height="24" width="24" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"><path d="M12.604 1.34c.393.69.784 1.382 1.174 2.075a.18.18 0 00.157.091h5.552c.174 0 .322.11.446.327l1.454 2.57c.19.337.24.478.024.837-.26.43-.513.864-.76 1.3l-.367.658c-.106.196-.223.28-.04.512l2.652 4.637c.172.301.111.494-.043.77-.437.785-.882 1.564-1.335 2.34-.159.272-.352.375-.68.37-.777-.016-1.552-.01-2.327.016a.099.099 0 00-.081.05 575.097 575.097 0 01-2.705 4.74c-.169.293-.38.363-.725.364-.997.003-2.002.004-3.017.002a.537.537 0 01-.465-.271l-1.335-2.323a.09.09 0 00-.083-.049H4.982c-.285.03-.553-.001-.805-.092l-1.603-2.77a.543.543 0 01-.002-.54l1.207-2.12a.198.198 0 000-.197 550.951 550.951 0 01-1.875-3.272l-.79-1.395c-.16-.31-.173-.496.095-.965.465-.813.927-1.625 1.387-2.436.132-.234.304-.334.584-.335a338.3 338.3 0 012.589-.001.124.124 0 00.107-.063l2.806-4.895a.488.488 0 01.422-.246c.524-.001 1.053 0 1.583-.006L11.704 1c.341-.003.724.032.9.34zm-3.432.403a.06.06 0 00-.052.03L6.254 6.788a.157.157 0 01-.135.078H3.253c-.056 0-.07.025-.041.074l5.81 10.156c.025.042.013.062-.034.063l-2.795.015a.218.218 0 00-.2.116l-1.32 2.31c-.044.078-.021.118.068.118l5.716.008c.046 0 .08.02.104.061l1.403 2.454c.046.081.092.082.139 0l5.006-8.76.783-1.382a.055.055 0 01.096 0l1.424 2.53a.122.122 0 00.107.062l2.763-.02a.04.04 0 00.035-.02.041.041 0 000-.04l-2.9-5.086a.108.108 0 010-.113l.293-.507 1.12-1.977c.024-.041.012-.062-.035-.062H9.2c-.059 0-.073-.026-.043-.077l1.434-2.505a.107.107 0 000-.114L9.225 1.774a.06.06 0 00-.053-.031zm6.29 8.02c.046 0 .058.02.034.06l-.832 1.465-2.613 4.585a.056.056 0 01-.05.029.058.058 0 01-.05-.029L8.498 9.841c-.02-.034-.01-.052.028-.054l.216-.012 6.722-.012z"></path></svg>
+    **Qwen Code**
+
+    Sign in with your Qwen account. Access Qwen 3 Coder with a 1 million token context window.
+  </Card>
+</CardGroup>
+
+---
+
+## Which Model Should I Use?
+
+| Mode | What works | Recommendation |
+|------|------------|----------------|
+| **Chat Mode** | Any model, including local | Ollama or Gemini Flash |
+| **Agent Mode** | Cloud models only | Claude Opus 4.5, GPT-5, or Kimi K2.5 (open source) |
+
+<Warning>
+**Local LLMs aren't powerful for most agentic tasks yet.** They're great for Chat — asking questions about a page, summarizing, etc. But agent tasks need strong reasoning to click the right elements and handle multi-step workflows. Use Claude Opus 4.5, GPT-5, or Kimi K2.5 for agents.
+</Warning>
+
+---
+
+## Kimi K2.5 — In Partnership with Moonshot AI
+
+{/* <img src="/images/moonshot-partnership-banner.png" alt="BrowserOS x Moonshot AI" className="rounded-xl" /> */}
+
+BrowserOS has partnered with [Moonshot AI](https://www.kimi.com) to bring **Kimi K2.5** as a first-class provider. Kimi K2.5 is now the **recommended model** in BrowserOS and is set as the default provider.
+
+For a limited time, BrowserOS users get **extended usage limits** powered by Kimi K2.5. This means you can use the AI agent, chat, and other AI-powered features with increased limits at no cost.
+
+<CardGroup cols={2}>
+  <Card title="Open Source" icon="code-branch">
+    Fully open-source model you can inspect and trust.
+  </Card>
+  <Card title="Multimodal" icon="image">
+    Supports images out of the box, including screenshots and visual context.
+  </Card>
+  <Card title="Great for Agents" icon="robot">
+    Strong reasoning for browser automation, form filling, and multi-step workflows.
+  </Card>
+  <Card title="Affordable" icon="piggy-bank">
+    Excellent agentic performance at a fraction of the cost of other frontier models.
+  </Card>
+</CardGroup>
+
+<div id="moonshot" />
+
+### Why Kimi K2.5?
+
+Kimi K2.5 offers excellent performance for agentic tasks at a fraction of the cost of other frontier models. It supports images, has a 128,000 token context window, and delivers strong results on browser automation tasks. Combined with BrowserOS's open-source agent framework, this makes for a powerful and affordable AI browsing experience.
+
+### Bring Your Own Kimi API Key
+
+You can also bring your own Kimi API key if you want to use Kimi K2.5 beyond the extended usage period, or if you want your own dedicated limits.
+
+**Get your API key:**
+1. Go to [platform.moonshot.ai](https://platform.moonshot.ai) and create an account
+2. Navigate to the **API keys** section in your dashboard
+3. Click **Create new API key** and copy the key
+
+**Add to BrowserOS:**
+1. Go to `chrome://browseros/settings`
+2. Click **USE** on the **Moonshot AI** card
+3. Enter your API key (it will be encrypted and stored locally on your machine)
+4. The model is pre-configured to `kimi-k2.5` with a 128,000 context window
+5. Click **Save**
+
+<Tip>
+The base URL for the Kimi API (`https://api.moonshot.ai/v1`) is pre-filled automatically when you select the Moonshot AI provider template.
+</Tip>
+
+---
+
+## Cloud Providers
+
+Connect to powerful AI models using your API keys. Your keys stay on your machine — requests go directly to the provider.
+
+<AccordionGroup>
+  <div id="gemini" />
+  <Accordion title="Gemini (Free)" icon="google">
+    Gemini Flash is fast and free. Google gives you 20 requests per minute at no cost.
+
+    **Get your API key:**
+    1. Go to [aistudio.google.com](https://aistudio.google.com)
+    2. Click **Get API key** in the sidebar
+    3. Click **Create API key** and copy it
+
+    ![Get Gemini API key](/images/gemini-get-api-key.png)
+
+    **Add to BrowserOS:**
+    1. Go to `chrome://browseros/settings`
+    2. Click **USE** on the Gemini card
+    3. Set **Model ID** to `gemini-2.5-flash` (or `gemini-2.5-pro`, `gemini-3-pro-preview`, `gemini-3-flash-preview`)
+    4. Paste your API key
+    5. Check **Supports Images**, set **Context Window** to `1000000`
+    6. Click **Save**
+
+    ![Gemini config](/images/byollm--gemini-provider-config.png)
+  </Accordion>
+
+  <div id="claude" />
+  <Accordion title="Claude (Best for Agents)" icon="message-bot">
+    Claude Opus 4.5 gives the best results for Agent Mode.
+
+    **Get your API key:**
+    1. Go to [console.anthropic.com](https://console.anthropic.com/dashboard)
+    2. Click **API keys** in the sidebar
+    3. Click **Create Key** and copy it
+
+    ![Get Claude API key](/images/claude-api-keys.png)
+
+    **Add to BrowserOS:**
+    1. Go to `chrome://browseros/settings`
+    2. Click **USE** on the Anthropic card
+    3. Set **Model ID** to `claude-opus-4-5-20251101` (or `claude-sonnet-4-5-20250929`, `claude-haiku-4-5-20251001`)
+    4. Paste your API key
+    5. Check **Supports Images**, set **Context Window** to `200000`
+    6. Click **Save**
+
+    ![Claude config](/images/byollm--claude-provider-config.png)
+  </Accordion>
+
+  <div id="openai" />
+  <Accordion title="OpenAI" icon="brain">
+    GPT-5 is OpenAI's most capable model for both chat and agent tasks.
+
+    **Get your API key:**
+    1. Go to [platform.openai.com](https://platform.openai.com)
+    2. Click settings icon → **API keys**
+    3. Click **Create new secret key** and copy it
+
+    ![Get OpenAI API key](/images/openai-api-keys.png)
+
+    **Add to BrowserOS:**
+    1. Go to `chrome://browseros/settings`
+    2. Click **USE** on the OpenAI card
+    3. Set **Model ID** to `gpt-5` (or `gpt-5.2`, `gpt-5-mini`, `gpt-4.1`, `o4-mini`)
+    4. Paste your API key
+    5. Check **Supports Images**, set **Context Window** to `200000`
+    6. Click **Save**
+
+    ![OpenAI config](/images/byollm--openai-provider-config.png)
+  </Accordion>
+
+  <div id="openrouter" />
+  <Accordion title="OpenRouter" icon="shuffle">
+    Access 500+ models through one API.
+
+    **Get your API key:**
+    1. Go to [openrouter.ai](https://openrouter.ai) and sign up
+    2. Go to [openrouter.ai/keys](https://openrouter.ai/keys) and create a key
+
+    **Pick a model:**
+    Go to [openrouter.ai/models](https://openrouter.ai/models) and copy the model ID you want (e.g., `anthropic/claude-opus-4.5`, `google/gemini-2.5-flash`).
+
+    ![OpenRouter models](/images/openrouter-models.png)
+
+    **Add to BrowserOS:**
+    1. Go to `chrome://browseros/settings`
+    2. Click **USE** on the OpenRouter card
+    3. Paste the model ID and your API key
+    4. Set **Context Window** based on the model
+    5. Click **Save**
+
+    ![OpenRouter config](/images/byollm--openrouter-provider-config.png)
+  </Accordion>
+
+  <div id="azure" />
+  <Accordion title="Azure OpenAI" icon="microsoft">
+    Use OpenAI models hosted on your own Azure subscription for enterprise compliance and data residency.
+
+    **Prerequisites:**
+    1. An Azure subscription with access to [Azure OpenAI Service](https://portal.azure.com/#view/Microsoft_Azure_ProjectOxford/CognitiveServicesHub/~/OpenAI)
+    2. A deployed model (e.g., GPT-4o) in your Azure OpenAI resource
+
+    **Get your credentials:**
+    1. Go to [portal.azure.com](https://portal.azure.com) → **Azure OpenAI** resource
+    2. Navigate to **Keys and Endpoint**
+    3. Copy **Key 1** and your **Endpoint URL**
+
+    **Add to BrowserOS:**
+    1. Go to `chrome://browseros/settings`
+    2. Click **USE** on the Azure card
+    3. Set **Base URL** to your Azure endpoint (e.g., `https://your-resource.openai.azure.com/openai/deployments/your-deployment`)
+    4. Set **Model ID** to your deployment name
+    5. Paste your API key
+    6. Check **Supports Images**, set **Context Window** to `128000`
+    7. Click **Save**
+  </Accordion>
+
+  <div id="bedrock" />
+  <Accordion title="AWS Bedrock" icon="aws">
+    Access Claude, Llama, and other models through your AWS account with IAM-based authentication.
+
+    **Prerequisites:**
+    1. An AWS account with [Amazon Bedrock](https://docs.aws.amazon.com/bedrock/latest/userguide/getting-started.html) enabled
+    2. Model access granted in the Bedrock console for your desired models
+
+    **Get your credentials:**
+    1. Go to the [AWS Console](https://console.aws.amazon.com) → **IAM**
+    2. Create or use an existing access key with Bedrock permissions
+    3. Note your **Access Key ID**, **Secret Access Key**, and **Region**
+
+    **Add to BrowserOS:**
+    1. Go to `chrome://browseros/settings`
+    2. Click **USE** on the AWS Bedrock card
+    3. Set **Base URL** to your Bedrock endpoint (region-specific)
+    4. Set **Model ID** to the Bedrock model ID (e.g., `anthropic.claude-3-sonnet-20240229-v1:0`)
+    5. Paste your credentials
+    6. Check **Supports Images**, set **Context Window** to `200000`
+    7. Click **Save**
+  </Accordion>
+
+  <div id="openai-compatible" />
+  <Accordion title="OpenAI Compatible" icon="plug">
+    Connect to any provider that implements the OpenAI-compatible API format (e.g., Together AI, Fireworks, Groq, Perplexity).
+
+    **Add to BrowserOS:**
+    1. Go to `chrome://browseros/settings`
+    2. Click **USE** on the OpenAI Compatible card
+    3. Set **Base URL** to the provider's API endpoint
+    4. Set **Model ID** to the model you want to use
+    5. Paste your API key
+    6. Set **Supports Images** and **Context Window** based on the model
+    7. Click **Save**
+
+    <Tip>
+    Most newer AI providers support the OpenAI-compatible API format. Check your provider's docs for the base URL and available model IDs.
+    </Tip>
+  </Accordion>
+</AccordionGroup>
+
+---
+
+## Local Models
+
+<Card title="Local Model Guide" icon="server" href="/features/local-models">
+  Run AI completely offline with Ollama or LM Studio. Includes recommended models, context length setup, and configuration steps.
+</Card>
+
+---
+
+## Switching Between Models
+
+Use the model switcher in the Assistant panel to change providers anytime. The default provider is highlighted.
+
+![Model switcher](/images/byollm--switcher.png)
+
+<Tip>
+Use local models for sensitive work data. Switch to Claude for agent tasks that need complex reasoning.
+</Tip>

docs/features/chatgpt-pro-oauth.mdx

@@ -0,0 +1,56 @@
+---
+title: "ChatGPT Pro / Plus"
+description: "Use your ChatGPT subscription to power BrowserOS"
+---
+
+Connect your ChatGPT Pro or Plus subscription to BrowserOS and access GPT-5 Codex, GPT-5.4, and the full lineup of OpenAI's most advanced models — with up to 400K context. No API keys needed.
+
+## Setup
+
+**1.** Open BrowserOS and go to **Settings** (`chrome://browseros/settings`). You'll see the AI Providers section.
+
+![AI Settings screen](/images/setting-up-chatgpt/llm-screen.png)
+
+**2.** Click **USE** on the **ChatGPT Plus/Pro** card. You'll be prompted to sign in with your OpenAI account.
+
+![Login screen](/images/setting-up-chatgpt/login-screen.png)
+
+**3.** Sign in with the OpenAI account that has your ChatGPT Pro or Plus subscription active, and accept the authorization.
+
+![Accept authorization](/images/setting-up-chatgpt/accept-screen.png)
+
+**4.** Once authorized, ChatGPT will appear as a provider in your settings. Select a model and start using it.
+
+## Available Models
+
+| Model | Context Window |
+|-------|---------------|
+| `gpt-5.4` | 400K |
+| `gpt-5.3-codex` | 400K |
+| `gpt-5.2-codex` | 400K |
+| `gpt-5.2` | 200K |
+| `gpt-5.1-codex` | 400K |
+| `gpt-5.1-codex-max` | 400K |
+| `gpt-5.1-codex-mini` | 400K |
+| `gpt-5.1` | 200K |
+
+<Info>
+ChatGPT Pro subscribers have access to the full model lineup. ChatGPT Plus subscribers can access a subset of models depending on their plan. The available models will be shown automatically after you connect.
+</Info>
+
+<Tip>
+The Codex models (e.g., `gpt-5.3-codex`) are optimized for code and reasoning tasks — ideal for complex browser automation workflows that involve form filling, data extraction, and multi-step navigation.
+</Tip>
+
+## Reasoning Settings
+
+ChatGPT Pro includes additional settings for models that support reasoning:
+
+- **Reasoning Effort** — Control how much the model "thinks" before responding. Options: none, low, medium, high.
+- **Reasoning Summary** — Choose how reasoning is displayed. Options: auto, concise, detailed.
+
+These settings are available in the provider configuration after connecting.
+
+## Disconnecting
+
+To disconnect your OpenAI account, go to **Settings**, find the ChatGPT Plus/Pro provider, and click **Disconnect**. Your OAuth tokens will be immediately deleted from your machine.

docs/features/connect-mcps.mdx

@@ -0,0 +1,308 @@
+---
+title: "Connect Apps"
+description: "Connect 40+ apps to BrowserOS so the assistant can work with your email, calendar, projects, and more"
+---
+
+Connect your favorite apps to BrowserOS and let the assistant work across all of them. Read emails, check your calendar, create tasks, post messages, manage files, and more, all through natural conversation.
+
+<video
+  controls
+  className="w-full aspect-video rounded-xl"
+  src="https://pub-80f8a01e6e8b4239ae53a7652ef85877.r2.dev/resources/feature-videos/4-MCP.mp4"
+></video>
+
+## How It Works
+
+BrowserOS uses the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) to connect your apps. You do not need to install anything or manage API keys. Just sign in once and the assistant handles the rest.
+
+
+## Smart App Connection
+
+When you ask the assistant to do something that needs an app you have not connected yet, it shows an interactive card right in the conversation. You can connect the app with one click or choose to skip it. No need to set things up in advance.
+
+<Steps>
+  <Step title="You make a request">
+    Ask the assistant something like "What's on my calendar today?" or "Send an email to Sarah."
+  </Step>
+  <Step title="A connection card appears">
+    The assistant detects the app is not connected and shows a card explaining why connecting it would help. You get two choices: **Connect** or **Do it manually**.
+  </Step>
+  <Step title="You connect or skip">
+    - **Connect**: Opens a sign-in page. Authorize the app and the assistant continues with full integration access.
+    - **Do it manually**: The assistant skips the integration and navigates to the app's website directly using browser automation.
+  </Step>
+  <Step title="The assistant continues">
+    Once connected, the app stays linked for all future conversations. If you chose to skip, the assistant remembers and will not ask again.
+  </Step>
+</Steps>
+
+{/* <Frame caption="The assistant detects an unconnected app and shows a connection card">
+  <img src="/images/connect-apps-smart-connection.png" alt="Smart app connection prompt in chat" />
+</Frame> */}
+
+See [Smart Nudges](/features/smart-nudges#app-connection) for more details on how connection suggestions work.
+
+You can also connect apps ahead of time from the sidebar if you prefer.
+
+## Connect from the Sidebar
+
+<Steps>
+  <Step title="Open Connect Apps">
+    Click **Connect Apps** in the sidebar.
+  </Step>
+  <Step title="Add an app">
+    Click **Add built-in app** and select the app you want
+  </Step>
+  <Step title="Sign in">
+    Complete the OAuth sign-in when prompted
+  </Step>
+</Steps>
+
+<Frame caption="Connected apps show a green 'Authenticated' badge">
+  <img src="/images/connect-apps-settings.png" alt="Connected Apps settings page" />
+</Frame>
+
+## 40+ Supported Apps
+
+BrowserOS connects to over 40 apps across every category you need.
+
+<AccordionGroup>
+  <Accordion title="Email" icon="envelope">
+    | App | What you can do |
+    |-----|----------------|
+    | **Gmail** | Send, read, and search emails, manage drafts and labels |
+    | **Outlook Mail** | Send, read, and manage emails |
+    | **Resend** | Send transactional and marketing emails |
+  </Accordion>
+
+  <Accordion title="Calendar and Scheduling" icon="calendar">
+    | App | What you can do |
+    |-----|----------------|
+    | **Google Calendar** | Create events, find free time, manage calendars |
+    | **Outlook Calendar** | Schedule meetings, manage events |
+    | **Cal.com** | Schedule meetings, manage availability |
+  </Accordion>
+
+  <Accordion title="Messaging" icon="comments">
+    | App | What you can do |
+    |-----|----------------|
+    | **Slack** | Post messages, manage channels |
+    | **Discord** | Send messages, manage servers |
+    | **WhatsApp** | Send messages, manage conversations |
+    | **Microsoft Teams** | Chat, meet, and collaborate |
+  </Accordion>
+
+  <Accordion title="Development" icon="code">
+    | App | What you can do |
+    |-----|----------------|
+    | **GitHub** | Manage repos, issues, and pull requests |
+    | **GitLab** | Manage repos, issues, and merge requests |
+    | **Vercel** | Deploy and manage web applications |
+    | **Postman** | Test and manage APIs |
+    | **Cloudflare** | Manage domains, DNS, and security |
+    | **Supabase** | Manage databases and backend services |
+  </Accordion>
+
+  <Accordion title="Project Management" icon="list-check">
+    | App | What you can do |
+    |-----|----------------|
+    | **Linear** | Create issues, manage cycles and projects |
+    | **Jira** | Create issues, manage sprints |
+    | **Asana** | Organize and track team projects |
+    | **Monday** | Manage work and team collaboration |
+    | **ClickUp** | Manage tasks, projects, and workflows |
+  </Accordion>
+
+  <Accordion title="Documents and Productivity" icon="file-lines">
+    | App | What you can do |
+    |-----|----------------|
+    | **Notion** | Create pages, manage databases |
+    | **Google Docs** | Create and edit documents |
+    | **Google Sheets** | Create and edit spreadsheets |
+    | **Google Drive** | Upload, download, and manage files |
+    | **Google Forms** | Create and manage forms and surveys |
+    | **Confluence** | Create and manage documentation |
+    | **Airtable** | Manage bases, tables, and records |
+  </Accordion>
+
+  <Accordion title="File Storage" icon="folder-open">
+    | App | What you can do |
+    |-----|----------------|
+    | **Dropbox** | Store and share files |
+    | **OneDrive** | Store and sync files with Microsoft |
+    | **Box** | Manage and share enterprise files |
+  </Accordion>
+
+  <Accordion title="Design" icon="pen-ruler">
+    | App | What you can do |
+    |-----|----------------|
+    | **Figma** | Access and manage design files |
+    | **Canva** | Create and manage designs |
+  </Accordion>
+
+  <Accordion title="CRM and Marketing" icon="chart-line">
+    | App | What you can do |
+    |-----|----------------|
+    | **Salesforce** | Manage leads, contacts, and opportunities |
+    | **HubSpot** | Manage contacts, deals, and marketing |
+  </Accordion>
+
+  <Accordion title="E-commerce and Payments" icon="cart-shopping">
+    | App | What you can do |
+    |-----|----------------|
+    | **Shopify** | Manage products, orders, and store |
+    | **Stripe** | Manage payments and subscriptions |
+  </Accordion>
+
+  <Accordion title="Analytics" icon="chart-bar">
+    | App | What you can do |
+    |-----|----------------|
+    | **PostHog** | Query analytics, manage feature flags |
+    | **Mixpanel** | Analyze user behavior and metrics |
+  </Accordion>
+
+  <Accordion title="Support" icon="headset">
+    | App | What you can do |
+    |-----|----------------|
+    | **Zendesk** | Manage support tickets and customers |
+    | **Intercom** | Manage customer messaging and support |
+  </Accordion>
+
+  <Accordion title="Search and AI" icon="magnifying-glass">
+    | App | What you can do |
+    |-----|----------------|
+    | **Brave Search** | Search the web privately |
+    | **Exa** | AI-powered semantic web search |
+    | **Mem0** | Store and retrieve AI memory |
+  </Accordion>
+
+  <Accordion title="Social and Content" icon="share-nodes">
+    | App | What you can do |
+    |-----|----------------|
+    | **LinkedIn** | Post updates, manage connections |
+    | **YouTube** | Access video info and transcripts |
+    | **WordPress** | Manage websites and blog content |
+  </Accordion>
+</AccordionGroup>
+
+## Example Prompts
+
+The assistant figures out which apps to use based on what you ask. Just describe what you want in plain language.
+
+<AccordionGroup>
+  <Accordion title="Calendar" icon="calendar">
+    - What's on my calendar today?
+    - Schedule a meeting with Sarah tomorrow at 2pm
+    - When is my next meeting with the marketing team?
+    - Block off Friday afternoon for focus time
+  </Accordion>
+  <Accordion title="Email" icon="envelope">
+    - Show me unread emails from my manager
+    - Draft a reply to the last email from John thanking him for the update
+    - Find emails about the Q4 budget from last week
+    - Send an email to the team with the meeting notes
+  </Accordion>
+  <Accordion title="Messaging" icon="hashtag">
+    - Post a message to #general saying I'll be out tomorrow
+    - What's the latest message in #engineering?
+    - Send a DM to Sarah asking if she's free for lunch
+    - Summarize what was discussed in #product today
+  </Accordion>
+  <Accordion title="Project Management" icon="list-check">
+    - Create a new Linear issue for the homepage redesign
+    - What are my open tasks in Jira?
+    - Move the "Launch campaign" task to complete in Asana
+    - Add a comment to the latest ClickUp task
+  </Accordion>
+  <Accordion title="Documents" icon="cube">
+    - Add "Review Q4 report" to my Notion tasks database
+    - Create a new page in my Projects database for the website redesign
+    - What are my open tasks in Notion?
+    - Update the status of the "Launch campaign" task to complete
+  </Accordion>
+</AccordionGroup>
+
+## Cross-App Workflows
+
+The real power of connected apps is combining them in a single request. The assistant can pull data from one app and use it in another without you switching between tabs.
+
+<CardGroup cols={2}>
+  <Card title="Email to task" icon="envelope">
+    "Find action items in my latest emails and add them to my Notion tasks"
+  </Card>
+  <Card title="Meeting prep" icon="calendar">
+    "Check my calendar for tomorrow, then draft an email to John summarizing what we're meeting about"
+  </Card>
+  <Card title="Bug triage" icon="bug">
+    "Test the checkout flow on our staging site, file a Linear issue if anything is broken, and post a summary to #engineering on Slack"
+  </Card>
+  <Card title="Sales pipeline" icon="chart-line">
+    "Pull my open deals from Salesforce and create a summary spreadsheet in Google Sheets"
+  </Card>
+  <Card title="Content roundup" icon="newspaper">
+    "Check the latest pull requests on our main repo and post a daily summary to #dev-updates on Slack"
+  </Card>
+  <Card title="Expense tracking" icon="receipt">
+    "Find all receipts in my Gmail from this month and organize them in a Google Sheet"
+  </Card>
+</CardGroup>
+
+## Add a Custom MCP Server
+
+You can connect any MCP-compatible server that exposes an SSE endpoint.
+
+1. Go to **Settings > Connected Apps**
+2. Click **Add custom app**
+3. Enter your server URL (e.g., `http://localhost:8000/sse`) and give it a name
+
+Custom servers appear alongside built-in apps and work the same way.
+
+<Tip>
+MCP has a growing ecosystem of servers. Browse [MCP servers on GitHub](https://github.com/modelcontextprotocol/servers) to find integrations for databases, APIs, and more.
+</Tip>
+
+### Connect to OAuth-Protected Remote Servers
+
+Some remote MCP servers (like Atlassian Jira, GitHub, etc.) require OAuth authentication. Use [mcp-remote](https://www.npmjs.com/package/mcp-remote) and [supergateway](https://github.com/supercorp-ai/supergateway) to handle the OAuth flow locally:
+
+```bash
+npx -y supergateway --stdio "npx -y mcp-remote https://mcp.atlassian.com/v1/sse" --port 8000
+```
+
+A browser window will open to sign in. Once authenticated, add `http://localhost:8000/sse` as a custom MCP in BrowserOS.
+
+<Note>
+Keep the terminal running while you use BrowserOS. The local server handles authentication and proxies requests to the remote MCP server.
+</Note>
+
+<AccordionGroup>
+  <Accordion title="Example: Atlassian Jira" icon="jira" iconType="brands">
+    ```bash
+    npx -y supergateway --stdio "npx -y mcp-remote https://mcp.atlassian.com/v1/sse" --port 8000
+    ```
+    Then add `http://localhost:8000/sse` as a custom MCP.
+  </Accordion>
+  <Accordion title="Example: GitHub" icon="github" iconType="brands">
+    ```bash
+    npx -y supergateway --stdio "npx -y mcp-remote https://api.githubcopilot.com/mcp/sse" --port 8001
+    ```
+    Then add `http://localhost:8001/sse` as a custom MCP.
+  </Accordion>
+</AccordionGroup>
+
+## Privacy and Security
+
+<Columns cols={2}>
+  <Card title="Secure OAuth" icon="shield-check">
+    All apps use OAuth sign-in. BrowserOS never sees or stores your passwords.
+  </Card>
+  <Card title="On-demand only" icon="clock">
+    Apps are only accessed when you ask. Nothing runs in the background.
+  </Card>
+  <Card title="You control access" icon="toggle-on">
+    Connect or disconnect any app at any time from Settings.
+  </Card>
+  <Card title="Credentials stay local" icon="lock">
+    Your authentication tokens are managed securely and stored locally on your machine.
+  </Card>
+</Columns>

docs/features/cowork.mdx

@@ -0,0 +1,222 @@
+---
+title: "Cowork"
+description: "Give the agent controlled access to local files and commands alongside browser automation"
+---
+
+Cowork lets you describe complex tasks and let the agent handle them end-to-end. It combines browser automation with local file operations: research on the web, then save reports directly to your folder. Read code, edit files, run shell commands, and search through your project, all in the same session as your browser tasks.
+
+Here's what it looks like to give the agent access to your local files:
+
+<video
+  controls
+  className="w-full aspect-video rounded-xl"
+  src="https://pub-80f8a01e6e8b4239ae53a7652ef85877.r2.dev/resources/feature-videos/3-filesystem-access.mp4"
+></video>
+
+## Why Cowork?
+
+Without Cowork, the agent can only interact with browser tabs. With Cowork enabled, it gains full access to a folder on your machine through 7 filesystem tools:
+
+<CardGroup cols={3}>
+  <Card title="Read & write files" icon="file-lines">
+    Read documents and data files, write reports, markdown, HTML, and other outputs
+  </Card>
+  <Card title="Edit files" icon="pen-to-square">
+    Make targeted edits to existing files with surgical string replacement
+  </Card>
+  <Card title="Run commands" icon="terminal">
+    Execute shell commands within the sandboxed folder
+  </Card>
+  <Card title="Search content" icon="magnifying-glass">
+    Search file contents with regex or literal patterns across your project
+  </Card>
+  <Card title="Find files" icon="folder-tree">
+    Find files by glob pattern, with smart filtering of build directories
+  </Card>
+  <Card title="Browse directories" icon="list">
+    List directory contents with file sizes, sorted and organized
+  </Card>
+</CardGroup>
+
+The real power: do both browser automation AND file operations in a single task. Describe what you want, step away, and come back to finished work.
+
+## Setting Up Cowork
+
+<Steps>
+  <Step title="Open the Cowork selector">
+    Click the **Cowork** dropdown next to the prompt input
+  </Step>
+  <Step title="Choose a folder">
+    Select a recent folder or click **Choose a different folder**
+  </Step>
+  <Step title="Grant access">
+    Allow BrowserOS to access that folder when prompted
+  </Step>
+</Steps>
+
+<Frame caption="Select a folder for the agent to operate in">
+  <img src="/features/cowork/cowork-selector.png" alt="Select a folder for the agent to operate in" />
+</Frame>
+
+The agent is sandboxed to your selected folder. It cannot access files outside of it.
+
+<Note>
+Cowork is available in **Agent Mode** only. In Chat Mode, the agent works with browser tabs only.
+</Note>
+
+<Tip>
+To disable file access, select **No folder** and the agent will work with browser tabs only.
+</Tip>
+
+## Filesystem Tools
+
+Cowork provides 7 filesystem tools that the agent can use alongside browser automation:
+
+<AccordionGroup>
+  <Accordion title="filesystem_read" icon="file-import">
+    Read a file from the filesystem. Returns text content with line numbers, or image data for image files (PNG, JPG, GIF, WEBP, BMP, SVG, ICO). Supports pagination through large files with `offset` and `limit` parameters.
+
+    | Parameter | Type | Description |
+    |-----------|------|-------------|
+    | `path` | string (required) | File path relative to working directory |
+    | `offset` | number (optional) | Starting line number (1-indexed) |
+    | `limit` | number (optional) | Max lines to read |
+
+    Responses are capped at 2000 lines or 50KB per request.
+  </Accordion>
+
+  <Accordion title="filesystem_write" icon="file-export">
+    Create or overwrite a file. Automatically creates parent directories if they don't exist.
+
+    | Parameter | Type | Description |
+    |-----------|------|-------------|
+    | `path` | string (required) | File path relative to working directory |
+    | `content` | string (required) | Complete file content to write |
+  </Accordion>
+
+  <Accordion title="filesystem_edit" icon="pen-to-square">
+    Make a targeted edit by replacing an exact string match. If the exact match fails, a whitespace-tolerant fuzzy match is attempted. Preserves original line endings (CRLF, CR, LF) and BOM.
+
+    | Parameter | Type | Description |
+    |-----------|------|-------------|
+    | `path` | string (required) | File path relative to working directory |
+    | `old_string` | string (required) | Exact text to find |
+    | `new_string` | string (required) | Replacement text |
+
+    Returns a side-by-side diff of the change.
+  </Accordion>
+
+  <Accordion title="filesystem_bash" icon="terminal">
+    Execute a shell command and return its output. Commands run in `sh`/`bash` on Unix or `cmd` on Windows.
+
+    | Parameter | Type | Description |
+    |-----------|------|-------------|
+    | `command` | string (required) | Shell command to execute |
+    | `timeout` | number (optional) | Timeout in seconds (default: 120) |
+
+    Output is truncated to the last 2000 lines if too large. Returns the exit code on failure.
+  </Accordion>
+
+  <Accordion title="filesystem_find" icon="folder-tree">
+    Find files matching a glob pattern. Searches recursively while skipping common build directories (`node_modules`, `.git`, `dist`, `build`, `.next`, `coverage`, `__pycache__`, and more).
+
+    | Parameter | Type | Description |
+    |-----------|------|-------------|
+    | `pattern` | string (required) | Glob pattern (e.g., `*.ts`, `**/*.json`) |
+    | `path` | string (optional) | Directory to search (default: working directory) |
+    | `limit` | number (optional) | Max results (default: 1000) |
+
+    Returns relative file paths sorted alphabetically.
+  </Accordion>
+
+  <Accordion title="filesystem_grep" icon="magnifying-glass">
+    Search file contents using regex or literal string matching. Skips binary files and files over 2MB.
+
+    | Parameter | Type | Description |
+    |-----------|------|-------------|
+    | `pattern` | string (required) | Search pattern (regex by default) |
+    | `path` | string (optional) | Directory or file to search |
+    | `glob` | string (optional) | Filter files by glob (e.g., `*.ts`) |
+    | `ignore_case` | boolean (optional) | Case-insensitive search |
+    | `literal` | boolean (optional) | Treat pattern as literal string |
+    | `context` | number (optional) | Lines of context around matches |
+    | `limit` | number (optional) | Max matches (default: 100) |
+  </Accordion>
+
+  <Accordion title="filesystem_ls" icon="list">
+    List directory contents. Shows directories first (with trailing `/`), then files with human-readable sizes.
+
+    | Parameter | Type | Description |
+    |-----------|------|-------------|
+    | `path` | string (optional) | Directory path (default: working directory) |
+    | `limit` | number (optional) | Max entries (default: 500) |
+
+    Entries are sorted alphabetically, case-insensitive.
+  </Accordion>
+</AccordionGroup>
+
+## Try It: Research and Create a Report
+
+With Cowork enabled, try this prompt:
+
+```
+Read the top 3 stories on Hacker News, read the comments too, and write an HTML report.
+```
+
+The agent will:
+
+<Steps>
+  <Step title="Navigate to Hacker News">
+    Opens the site and identifies top stories
+  </Step>
+  <Step title="Read stories and comments">
+    Clicks into each story and reads discussion threads
+  </Step>
+  <Step title="Generate report">
+    Creates an HTML report summarizing the findings
+  </Step>
+  <Step title="Save to folder">
+    Writes the report to your selected folder
+  </Step>
+</Steps>
+
+<Frame caption="Agent researching Hacker News and generating an HTML report">
+  <img src="/features/cowork/cowork-research-example.png" alt="Agent researching Hacker News and generating an HTML report" />
+</Frame>
+
+## Example Use Cases
+
+<AccordionGroup>
+  <Accordion title="Organize your downloads" icon="folder-tree">
+    > Go through my Downloads folder and organize files by type: documents, images, videos, archives.
+  </Accordion>
+  <Accordion title="Competitive research report" icon="magnifying-glass-chart">
+    > Research key trends about [topic] on Reddit, Twitter, and LinkedIn. Create an HTML report with your findings.
+  </Accordion>
+  <Accordion title="Web scraping to files" icon="spider-web">
+    > Visit these 10 product pages, extract the name, price, and description, and save the results as a markdown file.
+  </Accordion>
+  <Accordion title="Content aggregation" icon="newspaper">
+    > Find the top posts from these 5 subreddits today and compile them into a daily digest document.
+  </Accordion>
+  <Accordion title="Codebase exploration" icon="code">
+    > Search my project for all TODO comments, list them with file paths and line numbers, then create a summary markdown file.
+  </Accordion>
+  <Accordion title="Log analysis" icon="file-lines">
+    > Grep through the log files in this folder for errors from the last 24 hours and write a summary of what went wrong.
+  </Accordion>
+</AccordionGroup>
+
+## Security
+
+<CardGroup cols={3}>
+  <Card title="Sandboxed access" icon="box">
+    The agent can only access the folder you select. No parent directories, no path traversal.
+  </Card>
+  <Card title="Revoke anytime" icon="ban">
+    Select **No folder** to instantly disable file access
+  </Card>
+  <Card title="Local only" icon="house-laptop">
+    All file operations happen locally on your machine
+  </Card>
+</CardGroup>

docs/features/github-copilot-oauth.mdx

@@ -0,0 +1,60 @@
+---
+title: "GitHub Copilot"
+description: "Use your GitHub Copilot subscription to power BrowserOS"
+---
+
+Connect your GitHub Copilot subscription to BrowserOS and access 19+ models — including Claude, GPT-5, and Gemini — through a single GitHub sign-in. No API keys needed.
+
+<Info>
+**Free tier** includes GPT-5 Mini, Claude Haiku 4.5, GPT-4o, and GPT-4.1. **Copilot Pro** ($10/month) unlocks Claude Sonnet 4.6, Claude Opus 4.6, Gemini 3 Pro, GPT-5.4, and more.
+</Info>
+
+## Setup
+
+**1.** Open BrowserOS and go to **Settings** (`chrome://browseros/settings`). You'll see the AI Providers section.
+
+![AI Settings screen](/images/setting-up-copilot/llm-screen.png)
+
+**2.** Click **USE** on the **GitHub Copilot** card. A device code will appear — copy it, then click the link to open GitHub's device authorization page.
+
+![Device code displayed](/images/setting-up-copilot/device-code.png)
+
+**3.** Select your GitHub account to authorize.
+
+![Select GitHub account](/images/setting-up-copilot/select-account.png)
+
+**4.** Paste the device code and authorize BrowserOS to access your Copilot subscription.
+
+![Authorize device](/images/setting-up-copilot/authorize-device.png)
+
+**5.** Once authorized, GitHub Copilot will appear as a provider in your settings. Select a model and start using it.
+
+## Available Models
+
+### Free Tier
+| Model | Context Window |
+|-------|---------------|
+| `gpt-5-mini` | 128K |
+| `claude-haiku-4.5` | 128K |
+| `gpt-4o` | 64K |
+| `gpt-4.1` | 64K |
+
+### Copilot Pro / Pro+
+| Model | Context Window |
+|-------|---------------|
+| `claude-sonnet-4.6` | 200K |
+| `claude-opus-4.6` | 200K |
+| `gemini-2.5-pro` | 1M |
+| `gemini-3-pro-preview` | 1M |
+| `gpt-5.4` | 400K |
+| `gpt-5.3-codex` | 400K |
+| `gpt-5.2-codex` | 400K |
+| `grok-code-fast-1` | 128K |
+
+<Tip>
+GitHub Copilot is the most versatile provider — one subscription gives you access to models from OpenAI, Anthropic, Google, and xAI. Great if you want to switch between models for different tasks.
+</Tip>
+
+## Disconnecting
+
+To disconnect your GitHub account, go to **Settings**, find the GitHub Copilot provider, and click **Disconnect**. Your OAuth tokens will be immediately deleted from your machine.

docs/features/llm-chat-hub.mdx

@@ -0,0 +1,68 @@
+---
+title: "Chat & Hub"
+description: "Access ChatGPT, Claude, and Gemini from any webpage with one click"
+---
+
+BrowserOS puts AI chat at your fingertips. Open a chat panel on any webpage to ask questions with full page context, or compare responses across multiple LLMs side-by-side.
+
+Watch the chat panel and LLM Hub in action:
+
+<video
+  controls
+  className="w-full aspect-video rounded-xl"
+  src="https://pub-80f8a01e6e8b4239ae53a7652ef85877.r2.dev/resources/feature-videos/2-llm-chat-hub.mp4"
+></video>
+
+## LLM Chat
+
+Click the **Chat** button in the toolbar (or press `Option+K`) to open an AI chat panel on any webpage.
+
+<img src="/images/features--llm-chat-panel.png" alt="LLM Chat panel open on a webpage" />
+
+### Features
+
+- **Switch providers instantly** — Use the dropdown or press `Option+L` to cycle between Claude, ChatGPT, and Gemini
+- **Copy page context** — Grab the current webpage content to paste into your prompt
+- **Screenshot and attach** — Capture the visible page as an image for visual questions
+- **Works everywhere** — The panel stays open as you browse
+
+### Toolbar Buttons
+
+<img src="/images/features--llm-chat-toolbar.png" alt="LLM Chat toolbar buttons" />
+
+| Icon | Action |
+|------|--------|
+| Copy | Copy webpage content to clipboard |
+| Image | Screenshot webpage and copy |
+| Refresh | Reset LLM chat |
+| External | Open LLM in new tab |
+| Menu | Additional options + Popout LLM Hub |
+
+### Keyboard Shortcuts
+
+| Shortcut | Action |
+|----------|--------|
+| `Option+K` | Toggle chat panel |
+| `Option+L` | Switch to next provider |
+
+## LLM Hub (Clash of GPTs)
+
+Click the **Hub** button in the toolbar (or press `Cmd+Shift+U`) to open a multi-pane comparison window.
+
+<img src="/images/features--llm-hub.png" alt="LLM Hub with three panes showing Claude, Gemini, and ChatGPT" />
+
+The Hub lets you query multiple LLMs simultaneously:
+
+1. Choose 1, 2, or 3 panes using the panel selector in the top-right
+2. Select which LLM to use in each pane (Claude, Gemini, or ChatGPT)
+3. Paste your prompt into each pane and compare responses
+
+This is useful when you want an "LLM council" — get multiple perspectives on a question and see where the models agree or differ.
+
+## Customization
+
+Control which buttons appear in your toolbar from **Settings → Customization**:
+
+- **Show Chat Button** — Display the Chat button in the toolbar
+- **Show Hub Button** — Display the Hub button in the toolbar
+- **Show Button Labels** — Display text labels next to toolbar icons

docs/features/local-models.mdx

@@ -0,0 +1,120 @@
+---
+title: "Bring Your Local Model"
+description: "Run AI models locally with Ollama or LM Studio for free, private, offline use"
+---
+
+BrowserOS works great with local models for Chat Mode. Run models completely offline — your data never leaves your machine.
+
+## Context Length
+
+<Warning>
+**Ollama defaults to 4,096 tokens of context — this is too low for BrowserOS.** Below 15K tokens, the context overflows and the agent gets stuck in a loop constantly trying to recover. Only Chat Mode will work at low context lengths. Set at least **15,000–20,000 tokens** for local models to function properly.
+</Warning>
+
+Set context length when starting Ollama:
+
+```bash
+OLLAMA_CONTEXT_LENGTH=20000 ollama serve
+```
+
+<Info>
+Increasing context length uses more VRAM. Run `ollama ps` to check your current allocation. See the [Ollama context length docs](https://docs.ollama.com/context-length) for more details.
+</Info>
+
+---
+
+## Setup
+
+<Tabs>
+  <Tab title="Ollama" icon="terminal">
+    The easiest way to run models locally.
+
+    <Steps>
+      <Step title="Install Ollama">
+        Download from [ollama.com](https://ollama.com) and install it.
+      </Step>
+      <Step title="Pull a model">
+        ```bash
+        ollama pull qwen/qwen3-4b
+        ```
+      </Step>
+      <Step title="Start Ollama with higher context">
+        ```bash
+        OLLAMA_CONTEXT_LENGTH=20000 ollama serve
+        ```
+      </Step>
+      <Step title="Configure in BrowserOS">
+        1. Go to `chrome://browseros/settings`
+        2. Click **USE** on the Ollama card
+        3. Set **Model ID** to `qwen/qwen3-4b`
+        4. Set **Context Window** to `20000`
+        5. Click **Save**
+
+        ![Ollama in BrowserOS](/images/byollm--ollama-config.png)
+      </Step>
+    </Steps>
+  </Tab>
+  <Tab title="LM Studio" icon="desktop">
+    Nice GUI if you don't want to use the terminal.
+
+    <Steps>
+      <Step title="Install LM Studio">
+        Download from [lmstudio.ai](https://lmstudio.ai) and install it.
+      </Step>
+      <Step title="Load a model">
+        Open LM Studio → **Developer** tab → load a model. It runs a server at `http://localhost:1234/v1/`.
+
+        ![LM Studio](/images/setting-up-lm-studio/lmstudio-step1.png)
+      </Step>
+      <Step title="Configure in BrowserOS">
+        1. Go to `chrome://browseros/settings`
+        2. Click **USE** on the **OpenAI Compatible** card
+        3. Set **Base URL** to `http://localhost:1234/v1/`
+        4. Set **Model ID** to the model you loaded
+        5. Set **Context Window** to at least `20000`
+        6. Click **Save**
+
+        ![LM Studio in BrowserOS](/images/byollm--lmstudio-config.png)
+      </Step>
+    </Steps>
+  </Tab>
+</Tabs>
+
+---
+
+## Recommended Models
+
+Pick a model based on your available RAM/VRAM. Smaller models are faster but less capable.
+
+### Lightweight (under 5 GB)
+
+Good for machines with 8 GB RAM. Fast responses, suitable for simple chat tasks.
+
+| Model | Publisher | Params | Quant | Size |
+|-------|-----------|--------|-------|------|
+| `qwen/qwen3-4b` | Qwen | 4B | 4bit | 2.28 GB |
+| `mistralai/ministral-3-3b` | Mistral | 3B | Q4_K_M | 2.99 GB |
+| `deepseek-r1-distill-qwen-7b` | lmstudio-community | 7B | Q4_K_M | 4.68 GB |
+| `deepseek-r1-distill-llama-8b` | lmstudio-community | 8B | Q4_K_M | 4.92 GB |
+
+### Mid-range (10–15 GB)
+
+Needs 16+ GB RAM. Better reasoning, handles longer conversations well.
+
+| Model | Publisher | Params | Quant | Size |
+|-------|-----------|--------|-------|------|
+| `openai/gpt-oss-20b` | OpenAI | 20B | MXFP4 | 12.11 GB |
+| `mistralai/magistral-small` | Mistral | 23.6B | 4bit | 13.28 GB |
+| `mistralai/devstral-small-2-2512` | Mistral | 24B | 4bit | 14.12 GB |
+
+### Heavy (60+ GB)
+
+For workstations with 64+ GB RAM. Closest to cloud model quality.
+
+| Model | Publisher | Params | Quant | Size |
+|-------|-----------|--------|-------|------|
+| `openai/gpt-oss-120b` | OpenAI | 120B | MXFP4 | 63.39 GB |
+
+<Tip>
+Start with `qwen/qwen3-4b` if you're unsure — it's small, fast, and surprisingly capable for its size.
+</Tip>

docs/features/memory.mdx

@@ -0,0 +1,128 @@
+---
+title: "Memory"
+description: "Your assistant remembers what matters across every conversation"
+---
+
+The BrowserOS assistant has long-term memory. It remembers your name, your projects, the tools you use, and things that came up in past conversations. You do not need to repeat yourself. The assistant builds up knowledge about you over time and uses it to give better, more relevant answers.
+
+## How Memory Works
+
+Memory is automatic. As you chat, the assistant saves important facts and observations to local files on your machine. Before responding in future conversations, it searches these files to recall relevant context.
+
+<CardGroup cols={2}>
+  <Card title="Remembers you" icon="user">
+    Your name, job, location, projects, and preferences are stored permanently and recalled whenever relevant.
+  </Card>
+  <Card title="Keeps session notes" icon="note-sticky">
+    Useful details from each conversation are saved as daily notes and kept for 30 days.
+  </Card>
+  <Card title="Searches before answering" icon="magnifying-glass">
+    The assistant proactively searches its memory before responding, so it can reference things you have mentioned before.
+  </Card>
+  <Card title="Stays on your machine" icon="hard-drive">
+    All memory files are plain Markdown stored locally. Memory is never uploaded to the cloud, even with Sync to Cloud enabled.
+  </Card>
+</CardGroup>
+
+## Two Types of Memory
+
+BrowserOS uses a two-tier memory system to keep important facts separate from session notes.
+
+### Core Memory
+
+Core memory holds permanent facts about you. Things like your name, where you work, what projects you are working on, the tools and languages you use, and people you mention regularly. These facts persist forever and are never automatically deleted.
+
+Core memory lives in a single file called `CORE.md`. When the assistant learns something new about you, it reads the existing core memory, merges the new fact in, and saves the updated file.
+
+**Examples of what goes in core memory:**
+- Your name and role
+- Company and team
+- Projects you are working on
+- Tools, languages, and frameworks you use
+- People you mention often
+- Long-term preferences ("I prefer TypeScript over JavaScript")
+
+### Daily Memory
+
+Daily memory holds session notes, observations, and recent events. Each day gets its own file (e.g., `2026-03-07.md`), and entries are timestamped so the assistant can see when things happened.
+
+Daily memories automatically expire after **30 days**. If something keeps coming up, the assistant promotes it to core memory so it is not lost.
+
+**Examples of what goes in daily memory:**
+- Tasks you worked on today
+- Decisions made during a conversation
+- Temporary context ("meeting with Sarah moved to Thursday")
+- Research findings from a browsing session
+
+## Memory in Action
+
+You do not need to tell the assistant to remember things. It picks up on important details naturally. But you can also be explicit:
+
+<AccordionGroup>
+  <Accordion title="Automatic memory" icon="wand-magic-sparkles">
+    Just mention something in conversation and the assistant decides whether to save it:
+    - "I'm working on a project called Atlas at Acme Corp" -> saved to core memory
+    - "We decided to go with Postgres instead of MongoDB" -> saved to daily memory
+    - "My name is Sarah" -> saved to core memory
+  </Accordion>
+  <Accordion title="Ask it to remember" icon="bookmark">
+    Be explicit when you want something remembered:
+    - "Remember that our staging URL is staging.example.com"
+    - "Save this: the design review happens every Tuesday at 2pm"
+    - "Remember that I prefer dark mode in all my tools"
+  </Accordion>
+  <Accordion title="Ask it to recall" icon="rotate-left">
+    The assistant searches memory automatically, but you can also ask directly:
+    - "What do you remember about the Atlas project?"
+    - "What did we discuss yesterday?"
+    - "Do you know my team members' names?"
+  </Accordion>
+  <Accordion title="Ask it to forget" icon="eraser">
+    You can ask the assistant to remove specific memories:
+    - "Forget my phone number"
+    - "Remove the note about the staging URL"
+    - "Clear what you know about Project X"
+  </Accordion>
+</AccordionGroup>
+
+## Where Memory Lives
+
+All memory files are stored locally on your machine in the BrowserOS data folder:
+
+| File | Path | Purpose |
+|------|------|---------|
+| **Core memory** | `~/.browseros/memory/CORE.md` | Permanent facts about you |
+| **Daily notes** | `~/.browseros/memory/2026-03-07.md` | Session notes, auto-expire after 30 days |
+
+
+## Memory vs SOUL.md
+
+BrowserOS separates what the assistant **knows** from how it **behaves**. These are two different systems that work together.
+
+<Columns cols={2}>
+  <Card title="Memory" icon="brain">
+    **Facts about you and the world.** Your name, projects, preferences, recent events. Stored in CORE.md and daily files.
+  </Card>
+  <Card title="SOUL.md" icon="heart">
+    **How the assistant acts.** Personality, tone, communication style, boundaries. Stored in a single SOUL.md file. See [SOUL.md](/features/soul) for details.
+  </Card>
+</Columns>
+
+When the assistant learns that you work at Acme Corp, that goes in memory. When it learns that you prefer bullet points over paragraphs, that goes in SOUL.md. This separation means the assistant can change its personality without losing knowledge about you, and vice versa.
+
+## Privacy
+
+<Columns cols={2}>
+  <Card title="Never leaves your machine" icon="lock">
+    Memory files live on your machine and are never uploaded to any server. Even with Sync to Cloud enabled, memory stays local.
+  </Card>
+  <Card title="You control what is remembered" icon="toggle-on">
+    Ask the assistant to forget anything at any time. You can also directly edit or delete the memory files.
+  </Card>
+  <Card title="Plain text files" icon="file-lines">
+    Memory is stored as readable Markdown. No hidden databases or encrypted blobs. You can inspect everything.
+  </Card>
+  <Card title="30-day auto-cleanup" icon="clock">
+    Daily notes are automatically deleted after 30 days. Only facts you have promoted to core memory persist.
+  </Card>
+</Columns>

docs/features/qwen-code-oauth.mdx

@@ -0,0 +1,39 @@
+---
+title: "Qwen Code"
+description: "Use your Qwen Code account to power BrowserOS"
+---
+
+Connect your Qwen Code account to BrowserOS and access Alibaba's coding models with up to a **1 million token context window** — the largest of any provider we support. No API keys needed.
+
+## Setup
+
+**1.** Open BrowserOS and go to **Settings** (`chrome://browseros/settings`). You'll see the AI Providers section.
+
+![AI Settings screen](/images/setting-up-qwen/llm-screen.png)
+
+**2.** Click **USE** on the **Qwen Code** card. You'll be prompted to sign in with your Qwen account.
+
+![Select Qwen Code](/images/setting-up-qwen/select-qwen.png)
+
+**3.** Sign in with your Alibaba Cloud / Qwen account to authorize BrowserOS.
+
+![Qwen sign in](/images/setting-up-qwen/qwen-signin.png)
+
+**4.** Once authorized, Qwen Code will appear as a provider in your settings. Select a model and start using it.
+
+## Available Models
+
+| Model | Context Window |
+|-------|---------------|
+| `coder-model` | 1M |
+| `qwen3-coder-plus` | 1M |
+| `qwen3-coder-flash` | 1M |
+| `qwen3.5-plus` | 1M |
+
+<Tip>
+Qwen Code's 1 million token context window is ideal for tasks that involve long documents, entire documentation sites, or working across many browser tabs simultaneously — the agent can hold everything in context at once.
+</Tip>
+
+## Disconnecting
+
+To disconnect your Qwen account, go to **Settings**, find the Qwen Code provider, and click **Disconnect**. Your OAuth tokens will be immediately deleted from your machine.

docs/features/scheduled-tasks.mdx

@@ -0,0 +1,147 @@
+---
+title: "Scheduled Tasks"
+description: "Run the BrowserOS agent automatically on a schedule"
+---
+
+Scheduled Tasks let you run the BrowserOS agent automatically, whether it is daily, every few hours, or every few minutes. Write a prompt once, set a schedule, and let the agent handle it on autopilot.
+
+Watch how to set up a scheduled task from scratch:
+
+<video
+  controls
+  className="w-full aspect-video rounded-xl"
+  src="https://pub-80f8a01e6e8b4239ae53a7652ef85877.r2.dev/resources/feature-videos/5-scheduled-tasks.mp4"
+></video>
+
+## Creating a Scheduled Task
+
+There are two ways to create a scheduled task: from a conversation or from the settings page.
+
+### From a conversation
+
+After the agent completes a task that could run on a schedule, it will suggest scheduling it with an interactive card. You can also ask directly:
+
+- "Schedule this to run every morning"
+- "Can this run daily at 8am?"
+- "Automate this task"
+
+The agent fills in the task details for you. Just review and confirm. See [Smart Nudges](/features/smart-nudges#schedule-suggestion) for more details.
+
+### From settings
+
+<Steps>
+  <Step title="Open Scheduled Tasks">
+    Click **Scheduled Tasks** in the sidebar.
+  </Step>
+  <Step title="Click New Task">
+    Click the **New Task** button to open the creation dialog.
+  </Step>
+  <Step title="Fill in the details">
+    - **Name**: A friendly name for your task
+    - **Prompt**: What you want the agent to do (any natural language instruction)
+    - **Schedule type**: Daily at a specific time, every N hours, or every N minutes
+    - **Enable**: Toggle on to start running immediately
+  </Step>
+  <Step title="Create and go">
+    Click **Create**. The task will run at the next scheduled time automatically.
+  </Step>
+</Steps>
+
+<img src="/images/features--scheduled-tasks-create.png" alt="Create scheduled task dialog" />
+
+## Schedule Types
+
+<CardGroup cols={3}>
+  <Card title="Daily" icon="calendar-day">
+    Runs once a day at a specific time you choose (e.g., every morning at 8:00 AM).
+  </Card>
+  <Card title="Hourly" icon="clock">
+    Runs every N hours (e.g., every 2 hours, every 6 hours). Set an interval from 1 to 24 hours.
+  </Card>
+  <Card title="Minutes" icon="stopwatch">
+    Runs every N minutes (e.g., every 15 minutes, every 30 minutes). Set an interval from 1 to 60 minutes.
+  </Card>
+</CardGroup>
+
+## Example Use Cases
+
+<AccordionGroup>
+  <Accordion title="Morning briefing" icon="sun">
+    > Every morning at 8am, check my Google Calendar and send me a summary of today's events. For each meeting, do a quick Google search on the attendees and include their LinkedIn summary.
+  </Accordion>
+  <Accordion title="LinkedIn automation" icon="linkedin" iconType="brands">
+    > Every day, go to LinkedIn and accept up to 25 pending connection requests.
+  </Accordion>
+  <Accordion title="Price monitoring" icon="tag">
+    > Check the price of this Amazon item every hour. If it drops below $50, place the order.
+  </Accordion>
+  <Accordion title="Competitor tracking" icon="chart-line">
+    > Every morning at 9am, visit these 5 competitor websites and check for new product announcements or pricing changes. Summarize what is new.
+  </Accordion>
+  <Accordion title="Social media digest" icon="newspaper">
+    > Every evening at 6pm, check the top posts on Hacker News and r/programming. Create a brief summary of the most interesting discussions.
+  </Accordion>
+  <Accordion title="Cross-app workflow" icon="arrows-rotate">
+    > Check my Google Calendar for tomorrow's meetings, then post a summary to my Slack channel, and create a Notion page with prep notes for each meeting.
+  </Accordion>
+</AccordionGroup>
+
+Your scheduled task prompts can be as complex as you want. If you have [connected apps](/features/connect-mcps) like Google Calendar, Slack, Notion, or Gmail, your scheduled tasks can work across all of them.
+
+## Viewing Results
+
+When a scheduled task runs, you can see the results in two places:
+
+- **New Tab page**: Results show up right on your new tab
+- **Scheduled Tasks page**: View the full run history for each task
+
+<img src="/images/features--scheduled-tasks-results.png" alt="Scheduled task results" />
+
+Each task keeps a history of its last 15 runs. Click on any run to see the full output, including what tools the agent used and what it found.
+
+<img src="/images/features--scheduled-tasks-output.png" alt="Scheduled task output showing a daily news briefing" />
+
+You can also:
+- **Test** a task manually without waiting for the next scheduled run
+- **Retry** a failed task
+- **Cancel** a task that is currently running
+
+## How It Works
+
+<Steps>
+  <Step title="Task triggers on schedule">
+    BrowserOS uses your browser's built-in alarm system to trigger tasks at the right time. If your laptop was closed at the scheduled time, the task runs as soon as you open BrowserOS again.
+  </Step>
+  <Step title="Background window opens">
+    A hidden browser window opens automatically. The task runs there so it never interrupts whatever you are working on. You will not see anything happen on screen.
+  </Step>
+  <Step title="Agent executes your prompt">
+    The agent runs your prompt with full access to browser automation and any connected apps. It can navigate pages, fill forms, extract data, and interact with your services.
+  </Step>
+  <Step title="Results are saved">
+    When the task finishes, the result is saved and appears on your New Tab page and in the task's run history. The hidden window closes automatically.
+  </Step>
+</Steps>
+
+<Note>
+BrowserOS needs to be open for scheduled tasks to run. Tasks have a 10-minute timeout. If a task takes longer than that, it will be marked as failed and you can retry it.
+</Note>
+
+## Cloud Sync
+
+If you are signed in, your scheduled task configurations sync across devices. Create a task on your laptop and it appears on your desktop. Edits sync both ways, and conflicts are resolved automatically using timestamps.
+
+Only the schedule setup syncs (name, prompt, schedule type, and timing). Task run results and output stay on the device where the task ran.
+
+See [Sync to Cloud](/features/sync-to-cloud) for more details.
+
+## Privacy
+
+<Columns cols={2}>
+  <Card title="Runs locally" icon="house-laptop">
+    All tasks run on your machine in a hidden browser window. Nothing is sent to external servers.
+  </Card>
+  <Card title="Full control" icon="toggle-on">
+    Enable, disable, edit, or delete any task at any time. You decide what runs and when.
+  </Card>
+</Columns>

docs/features/skills.mdx

@@ -0,0 +1,193 @@
+---
+title: "Skills"
+description: "Teach your BrowserOS agent new abilities with reusable, custom instructions"
+---
+
+Skills let you teach the BrowserOS agent how to handle specific tasks. Each skill is a set of instructions written in plain Markdown that the agent loads when it recognizes a matching task. Think of skills as recipes: you write the steps once, and the agent follows them whenever that type of task comes up.
+
+BrowserOS implements the open [Agent Skills specification](https://agentskills.io/specification), so skills you create are portable across any AI agent that supports the standard.
+
+## How Skills Work
+
+<Steps>
+  <Step title="You create a skill">
+    Give it a name, a short description of when to use it, and write the instructions in Markdown.
+  </Step>
+  <Step title="The agent sees the skill catalog">
+    When a conversation starts, the agent loads a list of all your enabled skills with their names and descriptions.
+  </Step>
+  <Step title="The agent matches a task">
+    When your request matches a skill's description, the agent loads that skill's full instructions and follows them.
+  </Step>
+</Steps>
+
+## Creating a Skill
+
+<Steps>
+  <Step title="Open Skills settings">
+    Click **Skills** in the sidebar.
+  </Step>
+  <Step title="Click New Skill">
+    Click the **New Skill** button to open the creation form.
+  </Step>
+  <Step title="Fill in the details">
+    - **Name**: A short, descriptive name (e.g., "Morning Status Report")
+    - **Description**: Tell the agent when to use this skill. Be specific. For example: "When the user wants to read status updates from work across Notion, Linear, and Slack"
+    - **Content**: Write your instructions in Markdown. Include step-by-step directions, examples, and edge cases.
+  </Step>
+  <Step title="Save and enable">
+    Click **Create**. The skill is enabled by default and will be available to the agent immediately.
+  </Step>
+</Steps>
+
+<Tip>
+Write your description like a trigger. The agent uses it to decide whether to activate the skill. A good description says both **what** the skill does and **when** to use it.
+</Tip>
+
+## Example Skills
+
+<AccordionGroup>
+  <Accordion title="Morning status report">
+    **Description:** When the user wants to read status updates from work
+
+    **Instructions:**
+    ```markdown
+    Always look for updates in 3 sources:
+    1. **Notion** - Check the team updates page for any new entries from today
+    2. **Linear** - Look at issues assigned to the user that were updated in the last 24 hours
+    3. **Slack** - Check the #team-updates and #engineering channels for unread messages
+
+    Summarize everything in a single report grouped by source.
+    If a source has no updates, say so.
+    ```
+  </Accordion>
+
+  <Accordion title="PDF processing">
+    **Description:** Extract text and tables from PDF files, fill PDF forms, and merge multiple PDFs. Use when the user mentions PDFs, forms, or document extraction.
+
+    **Instructions:**
+    ```markdown
+    When extracting text from a PDF:
+    1. Download or open the PDF in the browser
+    2. Use the page content tool to extract visible text
+    3. Preserve table structure using Markdown tables
+    4. If the PDF has multiple pages, process each page
+
+    When filling a PDF form:
+    - Ask the user for the values if not provided
+    - Fill each field carefully and confirm before submitting
+
+    See references/FORMS.md for common form templates.
+    ```
+  </Accordion>
+
+  <Accordion title="Code review checklist">
+    **Description:** When the user asks to review code, a pull request, or wants feedback on code quality
+
+    **Instructions:**
+    ```markdown
+    Follow this checklist for every code review:
+    1. Check for security issues (XSS, injection, hardcoded secrets)
+    2. Look for performance problems (N+1 queries, unnecessary re-renders)
+    3. Verify error handling is present and meaningful
+    4. Check that naming is clear and consistent
+    5. Look for missing tests for new logic
+
+    Format your review as a list of findings with severity: Critical, Warning, or Suggestion.
+    Always start with what the code does well.
+    ```
+  </Accordion>
+</AccordionGroup>
+
+## Managing Skills
+
+From the Skills page, you can:
+
+- **Enable or disable** a skill using the toggle switch. Disabled skills are not loaded by the agent.
+- **Edit** a skill's name, description, or instructions by clicking the edit icon.
+- **Delete** a skill by clicking the trash icon. This removes the skill permanently.
+
+## Skill File Format
+
+Under the hood, each skill is stored as a `SKILL.md` file following the [Agent Skills specification](https://agentskills.io/specification):
+
+```markdown
+---
+name: morning-status-report
+description: When the user wants to read status updates from work
+metadata:
+  display-name: Morning Status Report
+  enabled: "true"
+---
+Always look for updates in 3 sources:
+1. Notion - Check the team updates page
+2. Linear - Look at assigned issues updated in the last 24 hours
+3. Slack - Check #team-updates and #engineering channels
+
+Summarize everything in a single report grouped by source.
+```
+
+The file uses YAML frontmatter for metadata and Markdown for the instructions.
+
+### Frontmatter fields
+
+| Field | Required | Description |
+|---|---|---|
+| `name` | Yes | Lowercase, hyphenated identifier (e.g., `morning-status-report`) |
+| `description` | Yes | When and how the agent should use this skill |
+| `license` | No | License for the skill |
+| `compatibility` | No | Environment requirements |
+| `metadata` | No | Extra fields like `display-name`, `enabled`, `version` |
+| `allowed-tools` | No | Restrict which tools the skill can use (experimental) |
+
+### Supporting files
+
+A skill can include additional directories alongside `SKILL.md`:
+
+- **`scripts/`** for executable code the agent can run
+- **`references/`** for detailed documentation loaded on demand
+- **`assets/`** for templates, images, or data files
+
+```
+morning-status-report/
+├── SKILL.md
+├── scripts/
+│   └── format-report.py
+└── references/
+    └── REFERENCE.md
+```
+
+The agent loads the main `SKILL.md` first. Supporting files are only loaded when the instructions reference them, keeping context usage efficient.
+
+## Where Skills Live
+
+Skills are stored as folders inside your BrowserOS configuration directory:
+
+| OS | Path |
+|---|---|
+| macOS | `~/.browseros/skills/` |
+| Windows | `%USERPROFILE%\.browseros\skills\` |
+| Linux | `~/.browseros/skills/` |
+
+Each skill gets its own folder named after the skill's `name` field.
+
+## Tips for Writing Good Skills
+
+<CardGroup cols={2}>
+  <Card title="Be specific in descriptions" icon="crosshairs">
+    Include keywords the agent can match against. "When the user asks about PDFs, forms, or document extraction" is better than "Helps with documents."
+  </Card>
+  <Card title="Keep instructions focused" icon="scissors">
+    A skill should do one thing well. Split complex workflows into multiple skills rather than one large one.
+  </Card>
+  <Card title="Include examples" icon="lightbulb">
+    Show the agent what good output looks like. Examples reduce ambiguity and improve results.
+  </Card>
+  <Card title="Use supporting files" icon="folder-tree">
+    Move detailed references to separate files. The agent loads them only when needed, saving context space.
+  </Card>
+</CardGroup>
+
+<Note>
+Skills follow the open [Agent Skills specification](https://agentskills.io/specification). Skills you create in BrowserOS work with any agent that supports the standard.
+</Note>

docs/features/smart-nudges.mdx

@@ -0,0 +1,117 @@
+---
+title: "Smart Nudges"
+description: "BrowserOS suggests app connections and task scheduling at the right moment"
+---
+
+Smart Nudges are context-aware suggestions that appear as interactive cards during a conversation. The agent detects opportunities to connect an app or schedule a task, and shows you a card at the right moment. You decide whether to act on it or skip it.
+
+There are two types of nudges: **App Connection** and **Schedule Suggestion**.
+
+## App Connection
+
+When you ask the agent to do something that involves an external app (like sending an email or checking your calendar), it checks whether that app is connected. If it is not, the agent shows a connection card before starting the task.
+
+<Steps>
+  <Step title="You make a request">
+    For example: "Send Sarah an email with the meeting notes."
+  </Step>
+  <Step title="The agent detects an unconnected app">
+    Gmail is not connected yet, so the agent cannot send emails through the integration.
+  </Step>
+  <Step title="A connection card appears">
+    The card explains why connecting the app would help and gives you two choices: **Connect** or **Do it manually**.
+  </Step>
+  <Step title="You choose">
+    - **Connect**: Opens a sign-in page for the app. Once you authorize, the agent continues with full integration access.
+    - **Do it manually**: The agent skips the integration and uses browser automation instead (navigates to the website directly).
+  </Step>
+</Steps>
+
+### What happens after you choose
+
+<CardGroup cols={2}>
+  <Card title="Connected" icon="circle-check">
+    The app is added to your connected list. The agent uses the integration for this and all future conversations. You can manage connected apps in [Connect Apps](/features/connect-mcps).
+  </Card>
+  <Card title="Declined" icon="forward">
+    The agent remembers your choice and will not ask about this app again. It uses browser automation to complete the task instead.
+  </Card>
+</CardGroup>
+
+<Tip>
+If you declined an app but change your mind later, you can connect it anytime from the [Connect Apps](/features/connect-mcps) settings page.
+</Tip>
+
+### Supported apps
+
+The agent can suggest connections for all 40+ built-in integrations, including Gmail, Google Calendar, Slack, Notion, GitHub, Linear, Jira, Figma, Salesforce, and many more. See [Connect Apps](/features/connect-mcps) for the full list.
+
+## Schedule Suggestion
+
+After the agent completes a task that could run on a recurring schedule, it shows a scheduling card. This helps you turn one-time tasks into automated routines without leaving the conversation.
+
+<Steps>
+  <Step title="The agent completes a task">
+    For example: "Here are the top 5 tech headlines from today."
+  </Step>
+  <Step title="The agent recognizes a schedulable task">
+    News gathering, price monitoring, report building, data tracking, and similar tasks that do not need your real-time input are good candidates.
+  </Step>
+  <Step title="A scheduling card appears">
+    The card suggests a name and schedule. For example: "Run this automatically? 'Morning News Briefing' - daily at 09:00."
+  </Step>
+  <Step title="You choose">
+    - **Schedule this task**: Opens the Scheduled Tasks page with the details pre-filled. Review and confirm to create the task.
+    - **Maybe later**: Dismisses the card. You can always create the scheduled task manually later.
+  </Step>
+</Steps>
+
+### You can also ask directly
+
+You do not have to wait for the agent to suggest it. Just tell the agent you want to schedule the task:
+
+<AccordionGroup>
+  <Accordion title="Example prompts" icon="message">
+    - "Schedule this to run every morning"
+    - "Can this run daily at 8am?"
+    - "Automate this task"
+    - "Run this every hour"
+
+    The agent will infer the task name, schedule type, and timing from your conversation and show the scheduling card immediately.
+  </Accordion>
+</AccordionGroup>
+
+### What gets scheduled
+
+The scheduling card pre-fills the [Scheduled Tasks](/features/scheduled-tasks) dialog with:
+
+- **Task name**: A short description based on the conversation
+- **Prompt**: The original query you asked the agent
+- **Schedule type**: Daily or hourly, based on what makes sense for the task
+- **Time**: A suggested time (for daily tasks)
+
+You can adjust any of these before confirming.
+
+## When Nudges Appear
+
+Nudges are designed to appear at the right moment without interrupting your workflow:
+
+| Nudge | When it appears | How often |
+|---|---|---|
+| App Connection | Before the agent starts working, when it detects an unconnected app | Once per app per conversation |
+| Schedule Suggestion | After the agent finishes a task that could be automated | Once per conversation |
+
+Nudges do not appear in:
+- **Scheduled tasks** running in the background
+- **Chat mode** (read-only, no browser automation)
+
+## Privacy
+
+<CardGroup cols={2}>
+  <Card title="Nothing is sent without your approval" icon="shield-check">
+    The agent only suggests a connection. No data is shared with the app until you explicitly authorize it.
+  </Card>
+  <Card title="Your choices are remembered locally" icon="hard-drive">
+    Declined apps are stored on your device. The agent will not ask about them again unless you reconnect from settings.
+  </Card>
+</CardGroup>

docs/features/soul.mdx

@@ -0,0 +1,126 @@
+---
+title: "SOUL.md"
+description: "Give your AI assistant a personality that grows with you"
+---
+
+Every time you start a new conversation, the BrowserOS assistant reads a file called `SOUL.md`. This file defines who the assistant is: how it talks, what it prioritizes, and how it behaves. Over time, it evolves based on your interactions, making the assistant feel less like a tool and more like _your_ assistant.
+
+## What is SOUL.md?
+
+SOUL.md is a plain text file that lives on your machine. It contains your assistant's personality, tone, communication style, rules, and boundaries.
+
+Think of it as a personal guide the assistant reads before every conversation. It shapes how the assistant responds to you, not what it knows. Facts about you (your name, projects, preferences) are stored separately in [memory](#soul-vs-memory).
+
+<Tip>
+The SOUL.md concept was pioneered by [OpenClaw](https://openclaw.ai/) and inspired by [soul.md](https://soul.md/), which explore the idea of giving AI systems a persistent identity through written documents. BrowserOS builds on this concept with a file that the assistant can read and rewrite on its own.
+</Tip>
+
+## How It Works
+
+When you first use BrowserOS, the assistant starts with a simple default personality:
+
+> _Be genuinely helpful. Have opinions when asked. Be resourceful before asking. Earn trust through competence._
+
+As you chat, the assistant picks up on how you like to communicate. If you prefer direct answers, it notices. If you set a boundary ("never send emails without asking me first"), it writes that into SOUL.md. Over time, the file becomes a reflection of how you and your assistant work together.
+
+<Steps>
+  <Step title="First conversation">
+    The assistant starts with a default template. It watches for cues about your preferred style, tone, and boundaries.
+  </Step>
+  <Step title="The assistant learns your style">
+    Based on your interactions, the assistant rewrites SOUL.md to reflect your preferences. It will briefly tell you when it makes a change.
+  </Step>
+  <Step title="Every future conversation">
+    The assistant reads the updated SOUL.md before responding, so your preferences carry over across sessions.
+  </Step>
+</Steps>
+
+You do not need to write or edit SOUL.md yourself. The assistant handles it. But you can always view it or ask the assistant to change it.
+
+## Viewing Your SOUL.md
+
+Open **Agent Soul** from the sidebar to see what your assistant's personality file looks like right now. The page shows the current contents of SOUL.md in a read-only viewer.
+
+{/* <Frame caption="View your assistant's personality in Settings">
+  <img src="/images/features/soul-settings.png" alt="Agent Soul settings page" />
+</Frame> */}
+
+## Shaping Your Assistant
+
+You do not need to edit the file directly. Just talk to your assistant. Here are some ways to shape its personality:
+
+<CardGroup cols={2}>
+  <Card title="Set the tone" icon="comment">
+    "Be more casual and direct. Skip the formalities."
+  </Card>
+  <Card title="Add a boundary" icon="shield">
+    "Never post to Slack or send emails without confirming with me first."
+  </Card>
+  <Card title="Change the personality" icon="masks-theater">
+    "Be more opinionated. If you think my approach is wrong, say so."
+  </Card>
+  <Card title="Start fresh" icon="rotate">
+    "Reset your personality to the default."
+  </Card>
+</CardGroup>
+
+The assistant will update SOUL.md based on your instructions and let you know what changed.
+
+## Where SOUL.md Lives
+
+SOUL.md is stored locally on your machine, inside the BrowserOS data folder:
+
+| Operating System | Path |
+|-----------------|------|
+| **macOS** | `~/.browseros/SOUL.md` |
+| **Windows** | `%APPDATA%/.browseros/SOUL.md` |
+| **Linux** | `~/.browseros/SOUL.md` |
+
+The file is plain Markdown, limited to 150 lines. You can open it in any text editor if you want to make manual edits, though we recommend letting the assistant manage it through conversation.
+
+## SOUL vs Memory
+
+BrowserOS keeps personality and knowledge separate on purpose.
+
+<Columns cols={2}>
+  <Card title="SOUL.md" icon="heart">
+    **How the assistant behaves.** Personality, tone, communication style, rules, and boundaries. One file, updated by rewriting the whole thing.
+  </Card>
+  <Card title="Memory" icon="brain">
+    **What the assistant knows about you.** Your name, projects, tools, preferences, and recent events. Stored as core facts and daily notes.
+  </Card>
+</Columns>
+
+When the assistant learns that you prefer bullet points over paragraphs, that goes in SOUL.md. When it learns that you work at Acme Corp on a project called Atlas, that goes in memory.
+
+This separation means the assistant can have a consistent personality even when its factual knowledge changes, and vice versa.
+
+## Example SOUL.md
+
+Here is what an evolved SOUL.md might look like after a few conversations:
+
+```markdown
+# SOUL.md
+
+## Personality
+- Direct and concise. No filler phrases.
+- Have opinions and share them when relevant.
+- Use humor sparingly but naturally.
+
+## Communication Style
+- Default to bullet points for lists and options.
+- Keep status updates to one or two lines.
+- When explaining something technical, use analogies.
+
+## Boundaries
+- Never send emails or post messages without explicit confirmation.
+- Do not make purchases or financial transactions.
+- Ask before modifying any file outside the current project.
+
+## Preferences
+- When researching, prioritize primary sources over summaries.
+- For code tasks, prefer simple solutions over clever ones.
+- Always explain trade-offs when suggesting approaches.
+```
+
+Your SOUL.md will look different because it is shaped by your conversations. No two are the same.

docs/features/sync-to-cloud.mdx

@@ -0,0 +1,120 @@
+---
+title: "Sync to Cloud"
+description: "Sign in to sync your conversations, settings, and automations across all your devices"
+---
+
+Sign in to BrowserOS and your data follows you everywhere. Your conversations, AI model settings, and scheduled tasks sync automatically to the cloud so you never lose your setup.
+
+## Why Sign In?
+
+Without an account, everything stays on one device. Sign in and your data is backed up and available wherever you use BrowserOS.
+
+<CardGroup cols={2}>
+  <Card title="Access anywhere" icon="laptop-mobile">
+    Open BrowserOS on a new device and your conversations, model settings, and scheduled tasks are already there.
+  </Card>
+  <Card title="Never lose your history" icon="clock-rotate-left">
+    Chat history is saved to the cloud automatically. Clear your browser data or switch machines and everything is still available.
+  </Card>
+  <Card title="Settings follow you" icon="sliders">
+    Set up your AI models once. Your provider configurations sync across devices so you never re-enter the same setup twice.
+  </Card>
+  <Card title="Automations stay in sync" icon="arrows-rotate">
+    Create a scheduled task on your laptop and it appears on your desktop. Edits sync both ways.
+  </Card>
+</CardGroup>
+
+## How to Sign In
+
+<Steps>
+  <Step title="Open a new tab">
+    Open a new tab in BrowserOS to see the home page.
+  </Step>
+  <Step title="Click Sign In">
+    Click **Sign In** in the sidebar to open the login page.
+  </Step>
+  <Step title="Choose your sign-in method">
+    Enter your email for a magic link, or sign in with Google.
+  </Step>
+  <Step title="Verify and you're in">
+    Click the link in your email (or complete Google sign-in). BrowserOS starts syncing your data immediately.
+  </Step>
+</Steps>
+
+<Tip>
+Magic link sign-in means you never need to create or remember a password. Just enter your email and click the link.
+</Tip>
+
+## What Gets Synced
+
+<AccordionGroup>
+  <Accordion title="Conversations" icon="messages">
+    Your full chat history syncs to the cloud as you go. Every message is saved in real time so you can pick up any conversation on another device. Locally, BrowserOS keeps your 50 most recent conversations. In the cloud, there is no limit.
+  </Accordion>
+
+  <Accordion title="AI model settings" icon="microchip">
+    Your configured LLM providers (OpenAI, Anthropic, Google, Moonshot, Azure, Bedrock, and others) sync across devices. This includes the model name, provider type, base URL, temperature, and context window settings.
+
+    **Your API keys are never synced.** Sensitive credentials like API keys, access keys, and session tokens stay on the device where you entered them. You will need to re-enter API keys on each new device.
+  </Accordion>
+
+  <Accordion title="Scheduled tasks" icon="calendar-check">
+    Your scheduled task configurations sync in both directions. Create a task on one device, edit it on another, and changes are merged automatically using timestamps to resolve conflicts. Only the schedule setup syncs (name, prompt, schedule type, and timing). Task run results and output stay on the device where the task ran.
+  </Accordion>
+
+  <Accordion title="Profile" icon="user">
+    Your name, profile picture, and account preferences sync across devices. Information you provide during onboarding (role, company) is also saved to your profile.
+  </Accordion>
+</AccordionGroup>
+
+## What Stays Local
+
+Some settings are device-specific and do not sync to the cloud:
+
+- **API keys and secrets** for LLM providers
+- **Memory** (core facts and daily notes)
+- **SOUL.md** (assistant personality)
+- **Theme** (light/dark mode)
+- **Workspace folder** selection
+- **Connected MCP servers**
+- **Workflows**
+- **Scheduled task results** (run output stays on the device where the task ran)
+
+This is intentional. Sensitive credentials never leave your device, memory and personality files stay private, and display preferences can differ between machines.
+
+## How Sync Works
+
+BrowserOS uses a local-first approach. Your data is always saved on your device first, then synced to the cloud in the background.
+
+<Steps>
+  <Step title="Local save">
+    Every action (sending a message, adding a provider, creating a task) is saved locally first. BrowserOS works fully offline.
+  </Step>
+  <Step title="Background sync">
+    When you are signed in, changes are automatically pushed to the cloud. New chat messages sync in real time. Provider and task changes sync whenever they are updated.
+  </Step>
+  <Step title="Restore on new devices">
+    When you sign in on a new device, BrowserOS pulls your conversations, model settings, scheduled tasks, and profile from the cloud and merges them with any local data.
+  </Step>
+</Steps>
+
+<Note>
+If the same scheduled task is edited on two devices before they sync, BrowserOS keeps the version with the most recent timestamp.
+</Note>
+
+## Security
+
+<Columns cols={2}>
+  <Card title="API keys never leave your device" icon="key">
+    Sensitive credentials like API keys, access keys, and tokens are excluded from cloud sync entirely.
+  </Card>
+  <Card title="Session-based authentication" icon="shield-check">
+    Sign-in uses magic links or Google OAuth. No passwords are stored.
+  </Card>
+  <Card title="Scoped to your account" icon="lock">
+    All synced data is tied to your user account and is not accessible to anyone else.
+  </Card>
+  <Card title="Sync failures are silent" icon="wifi-slash">
+    If cloud sync fails (e.g., no internet), your local data is unaffected. Sync resumes automatically when connectivity is restored.
+  </Card>
+</Columns>

docs/features/use-with-claude-code.mdx

@@ -0,0 +1,416 @@
+---
+title: "MCP Clients (Claude Code, OpenClaw)"
+description: "Control your browser and 40+ apps from Claude Code, OpenClaw, Gemini CLI, or any MCP client"
+---
+
+BrowserOS is the best browser for AI coding agents. It comes with a built-in MCP server that gives your AI agent **full browser control** and **direct access to 40+ external services** — Gmail, Slack, GitHub, Google Calendar, Linear, Notion, and more — all through a single MCP connection.
+
+<Note>
+Unlike Chrome DevTools MCP which requires setting up debug profiles and running separate servers, BrowserOS MCP works out of the box. Just copy the URL from settings and connect.
+</Note>
+
+## Why Use BrowserOS with Claude Code?
+
+<CardGroup cols={2}>
+  <Card title="Agentic Coding" icon="code">
+    Claude tests your web app, reads console errors, and fixes the code — all in one loop.
+  </Card>
+  <Card title="40+ App Integrations" icon="grid-2">
+    Gmail, Slack, GitHub, Jira, Notion, Google Sheets, and more — accessible directly from your AI agent.
+  </Card>
+  <Card title="Data Extraction" icon="download">
+    Extract your LinkedIn profile, tweets, or any authenticated page content.
+  </Card>
+  <Card title="Task Automation" icon="repeat">
+    Fill forms, navigate multi-step workflows, and automate repetitive browser tasks.
+  </Card>
+  <Card title="53+ MCP Tools" icon="wrench">
+    Full browser control: tabs, navigation, clicks, typing, screenshots, bookmarks, history, tab groups, and window management.
+  </Card>
+  <Card title="Zero Config Auth" icon="lock">
+    Connect external services via OAuth — credentials are managed securely, never stored in BrowserOS.
+  </Card>
+</CardGroup>
+
+<Tip>
+Wondering how BrowserOS MCP compares to Chrome DevTools MCP or other browser automation tools? See our [detailed feature comparison](/comparisons/chrome-devtools-mcp) covering 53 browser tools, 40+ app integrations, and why BrowserOS MCP gives developers more out of the box.
+</Tip>
+
+## Getting Started
+
+<Steps>
+  <Step title="Open BrowserOS Settings">
+    Navigate to `chrome://browseros/mcp` or click **Settings** → **BrowserOS as MCP** in the sidebar.
+  </Step>
+  <Step title="Copy the MCP URL">
+    Copy the Server URL shown on the page (e.g., `http://127.0.0.1:9239/mcp`).
+
+    <img src="/images/features--browseros-mcp-settings.png" alt="BrowserOS MCP settings page showing Server URL" />
+  </Step>
+  <Step title="Connect your MCP client">
+    Use the tabs below to connect your preferred client.
+  </Step>
+</Steps>
+
+<Tabs>
+  <Tab title="Claude Code">
+    Add BrowserOS to Claude Code:
+    ```bash
+    claude mcp add --transport http browseros <mcp_url> --scope user
+    # Example: claude mcp add --transport http browseros http://127.0.0.1:9239/mcp --scope user
+    ```
+
+    Start Claude Code and try it:
+    ```bash
+    claude
+    > Open amazon.com in BrowserOS
+    ```
+
+    <Tip>
+    Run `claude --dangerously-skip-permissions` to skip confirmation prompts for each browser action.
+    </Tip>
+
+    To remove later:
+    ```bash
+    claude mcp remove browseros --scope user
+    ```
+  </Tab>
+  <Tab title="Gemini CLI">
+    Add BrowserOS to Gemini CLI:
+    ```bash
+    gemini mcp add local-server <mcp_url> --transport http --scope user
+    # Example: gemini mcp add local-server http://127.0.0.1:9239/mcp --transport http --scope user
+    ```
+  </Tab>
+  <Tab title="Codex">
+    Add BrowserOS to OpenAI Codex CLI:
+    ```bash
+    codex mcp add browseros <mcp_url> --transport http
+    # Example: codex mcp add browseros http://127.0.0.1:9239/mcp --transport http
+    ```
+  </Tab>
+  <Tab title="OpenClaw">
+    Add BrowserOS to [OpenClaw](https://openclaw.ai/) by adding it to the `mcpServers` section in your `openclaw.json` config file:
+    ```json
+    {
+      "mcpServers": {
+        "browseros": {
+          "url": "http://127.0.0.1:9239/mcp"
+        }
+      }
+    }
+    ```
+
+    Replace the URL with your BrowserOS MCP URL from settings.
+  </Tab>
+  <Tab title="Claude Desktop">
+    Open your Claude Desktop config file:
+    ```
+    ~/Library/Application Support/Claude/claude_desktop_config.json
+    ```
+
+    Add BrowserOS:
+    ```json
+    {
+      "mcpServers": {
+        "browserOS": {
+          "command": "npx",
+          "args": ["mcp-remote", "http://127.0.0.1:9239/mcp"]
+        }
+      }
+    }
+    ```
+
+    Restart Claude Desktop to connect.
+  </Tab>
+</Tabs>
+
+## Example Prompts
+
+<Accordion title="Try these prompts once connected" icon="message">
+  Extract structured data from any page you're logged into — no scraping setup needed.
+  ```
+  Open my LinkedIn profile in BrowserOS and extract my work experience as JSON
+  ```
+
+  Test your web app end-to-end without leaving the terminal — Claude navigates, interacts, and reports errors back.
+  ```
+  In BrowserOS, go to localhost:3000, click the login button, and check for console errors
+  ```
+
+  Capture visual snapshots of any page for debugging, documentation, or design review.
+  ```
+  Take a screenshot of the current page in BrowserOS and save it to screenshots/
+  ```
+
+  Search through your real browsing history to find pages you visited earlier.
+  ```
+  Search my BrowserOS history for "invoice" and list the recent matches
+  ```
+
+  Access your email directly from the agent — read, search, and summarize without switching windows.
+  ```
+  Read my latest Gmail messages and summarize them
+  ```
+
+  Chain multiple services together in a single prompt — file issues, notify your team, and stay in flow.
+  ```
+  Create a Linear issue for the bug I just found and post a summary to Slack
+  ```
+</Accordion>
+
+---
+
+## Browser Automation Tools
+
+BrowserOS exposes **53 browser automation tools** to MCP clients, organized into the following categories:
+
+<AccordionGroup>
+  <Accordion title="Navigation & Tabs (8 tools)" icon="window-restore">
+    | Tool | Description |
+    |------|-------------|
+    | `get_active_page` | Get the currently focused page/tab |
+    | `list_pages` | List all open pages with title, URL, and tab ID |
+    | `navigate_page` | Navigate to a URL, or go back/forward/reload |
+    | `new_page` | Open a new tab (with optional background/hidden mode) |
+    | `new_hidden_page` | Open a hidden tab for background automation |
+    | `show_page` | Restore a hidden page to visible state |
+    | `move_page` | Move a tab to a different window or position |
+    | `close_page` | Close a tab |
+  </Accordion>
+
+  <Accordion title="Content & Observation (8 tools)" icon="eye">
+    | Tool | Description |
+    |------|-------------|
+    | `take_snapshot` | Get accessibility tree with interactive element IDs |
+    | `take_enhanced_snapshot` | Detailed accessibility tree with structural context |
+    | `get_page_content` | Extract page as clean Markdown (headers, links, tables) |
+    | `get_page_links` | Extract all links from a page with deduplication |
+    | `get_dom` | Get raw HTML DOM with optional CSS selector scoping |
+    | `search_dom` | Search DOM by text, CSS selector, or XPath |
+    | `take_screenshot` | Capture page screenshot (PNG/JPEG/WebP, full-page option) |
+    | `evaluate_script` | Execute JavaScript in the page context |
+  </Accordion>
+
+  <Accordion title="Interaction & Input (14 tools)" icon="hand-pointer">
+    | Tool | Description |
+    |------|-------------|
+    | `click` | Click an element by ID from snapshot |
+    | `click_at` | Click at specific X,Y coordinates |
+    | `hover` | Hover over an element |
+    | `focus` | Focus an element (scrolls into view) |
+    | `fill` | Type text into an input (with optional clear) |
+    | `clear` | Clear text from input/textarea |
+    | `check` | Check a checkbox or radio button |
+    | `uncheck` | Uncheck a checkbox |
+    | `select_option` | Select a dropdown option by value or text |
+    | `press_key` | Press a key or key combination (Enter, Ctrl+A, etc.) |
+    | `drag` | Drag an element to another element or coordinates |
+    | `scroll` | Scroll page or element (up/down/left/right) |
+    | `upload_file` | Upload files to a file input element |
+    | `handle_dialog` | Accept or dismiss JavaScript dialogs |
+  </Accordion>
+
+  <Accordion title="File & Export (3 tools)" icon="file-export">
+    | Tool | Description |
+    |------|-------------|
+    | `save_pdf` | Print current page to a PDF file |
+    | `save_screenshot` | Capture and save a screenshot to disk |
+    | `download_file` | Click an element to trigger a download and save it |
+  </Accordion>
+
+  <Accordion title="Window Management (5 tools)" icon="window-maximize">
+    | Tool | Description |
+    |------|-------------|
+    | `list_windows` | List all browser windows |
+    | `create_window` | Create a new browser window |
+    | `create_hidden_window` | Create a hidden window for background tasks |
+    | `close_window` | Close a window by ID |
+    | `activate_window` | Focus and activate a window |
+  </Accordion>
+
+  <Accordion title="Tab Groups (5 tools)" icon="layer-group">
+    | Tool | Description |
+    |------|-------------|
+    | `list_tab_groups` | List all tab groups |
+    | `group_tabs` | Create a tab group with optional title and color |
+    | `update_tab_group` | Update group title, color, or collapsed state |
+    | `ungroup_tabs` | Remove tabs from groups |
+    | `close_tab_group` | Close a group and all its tabs |
+  </Accordion>
+
+  <Accordion title="Bookmarks (6 tools)" icon="bookmark">
+    | Tool | Description |
+    |------|-------------|
+    | `get_bookmarks` | List all bookmarks |
+    | `create_bookmark` | Create a bookmark or folder |
+    | `remove_bookmark` | Delete a bookmark or folder |
+    | `update_bookmark` | Update bookmark title or URL |
+    | `move_bookmark` | Move a bookmark to a different folder |
+    | `search_bookmarks` | Search bookmarks by title or URL |
+  </Accordion>
+
+  <Accordion title="History (4 tools)" icon="clock-rotate-left">
+    | Tool | Description |
+    |------|-------------|
+    | `search_history` | Search browser history by text query |
+    | `get_recent_history` | Get the most recent history items |
+    | `delete_history_url` | Delete a specific URL from history |
+    | `delete_history_range` | Delete history within a time range |
+  </Accordion>
+</AccordionGroup>
+
+---
+
+## 40+ External App Integrations
+
+BrowserOS connects your AI agent directly to the tools you already use — no separate MCP servers to install or configure. Everything is accessible through the same BrowserOS MCP connection.
+
+### How It Works
+
+<Steps>
+  <Step title="Agent calls an external service tool">
+    Your AI agent calls a tool like `gmail_search_messages` through the BrowserOS MCP.
+  </Step>
+  <Step title="OAuth login (first time only)">
+    If this is your first time using that service, BrowserOS opens an OAuth login page in the browser. Log in and authorize access.
+  </Step>
+  <Step title="Tool executes and returns results">
+    Once authenticated, the tool runs and returns results to your agent. Future calls to the same service work automatically — no re-authentication needed.
+  </Step>
+</Steps>
+
+<Note>
+Your credentials are managed securely via OAuth and are **never stored in BrowserOS**. Tokens are refreshed transparently, and you can revoke access at any time from the service provider.
+</Note>
+
+### Supported Services
+
+<AccordionGroup>
+  <Accordion title="Email" icon="envelope">
+    | Service | What you can do |
+    |---------|----------------|
+    | **Gmail** | Send, read, search emails, manage drafts and labels |
+    | **Outlook Mail** | Send, read, and manage emails |
+    | **Resend** | Send transactional and marketing emails |
+  </Accordion>
+
+  <Accordion title="Calendar & Scheduling" icon="calendar">
+    | Service | What you can do |
+    |---------|----------------|
+    | **Google Calendar** | Create events, find free time, manage calendars |
+    | **Outlook Calendar** | Schedule meetings, manage events |
+    | **Cal.com** | Schedule meetings, manage availability |
+  </Accordion>
+
+  <Accordion title="Communication" icon="comments">
+    | Service | What you can do |
+    |---------|----------------|
+    | **Slack** | Post messages, manage channels |
+    | **Discord** | Send messages, manage servers |
+    | **WhatsApp** | Send messages, manage conversations |
+    | **Microsoft Teams** | Chat, meet, and collaborate |
+  </Accordion>
+
+  <Accordion title="Development" icon="code">
+    | Service | What you can do |
+    |---------|----------------|
+    | **GitHub** | Manage repos, issues, and pull requests |
+    | **GitLab** | Manage repos, issues, and merge requests |
+    | **Vercel** | Deploy and manage web applications |
+    | **Postman** | Test and manage APIs |
+    | **Cloudflare** | Manage domains, DNS, and security |
+    | **Supabase** | Manage databases and backend services |
+  </Accordion>
+
+  <Accordion title="Project Management" icon="list-check">
+    | Service | What you can do |
+    |---------|----------------|
+    | **Linear** | Create issues, manage cycles and projects |
+    | **Jira** | Create issues, manage sprints |
+    | **Asana** | Organize and track team projects |
+    | **Monday** | Manage work and team collaboration |
+    | **ClickUp** | Manage tasks, projects, and workflows |
+  </Accordion>
+
+  <Accordion title="Productivity & Docs" icon="file-lines">
+    | Service | What you can do |
+    |---------|----------------|
+    | **Notion** | Create pages, manage databases |
+    | **Google Docs** | Create and edit documents |
+    | **Google Sheets** | Create and edit spreadsheets |
+    | **Google Drive** | Upload, download, and manage files |
+    | **Google Forms** | Create and manage forms and surveys |
+    | **Confluence** | Create and manage documentation |
+    | **Airtable** | Manage bases, tables, and records |
+  </Accordion>
+
+  <Accordion title="File Storage" icon="folder-open">
+    | Service | What you can do |
+    |---------|----------------|
+    | **Dropbox** | Store and share files |
+    | **OneDrive** | Store and sync files with Microsoft |
+    | **Box** | Manage and share enterprise files |
+  </Accordion>
+
+  <Accordion title="Design" icon="pen-ruler">
+    | Service | What you can do |
+    |---------|----------------|
+    | **Figma** | Access and manage design files |
+    | **Canva** | Create and manage designs |
+  </Accordion>
+
+  <Accordion title="CRM & Marketing" icon="chart-line">
+    | Service | What you can do |
+    |---------|----------------|
+    | **Salesforce** | Manage leads, contacts, and opportunities |
+    | **HubSpot** | Manage contacts, deals, and marketing |
+  </Accordion>
+
+  <Accordion title="E-commerce & Payments" icon="cart-shopping">
+    | Service | What you can do |
+    |---------|----------------|
+    | **Shopify** | Manage products, orders, and store |
+    | **Stripe** | Manage payments and subscriptions |
+  </Accordion>
+
+  <Accordion title="Analytics" icon="chart-bar">
+    | Service | What you can do |
+    |---------|----------------|
+    | **PostHog** | Query analytics, manage feature flags |
+    | **Mixpanel** | Analyze user behavior and metrics |
+  </Accordion>
+
+  <Accordion title="Support" icon="headset">
+    | Service | What you can do |
+    |---------|----------------|
+    | **Zendesk** | Manage support tickets and customers |
+    | **Intercom** | Manage customer messaging and support |
+  </Accordion>
+
+  <Accordion title="Search & AI" icon="magnifying-glass">
+    | Service | What you can do |
+    |---------|----------------|
+    | **Brave Search** | Search the web privately |
+    | **Exa** | AI-powered semantic web search |
+    | **Mem0** | Store and retrieve AI memory |
+  </Accordion>
+
+  <Accordion title="Social" icon="share-nodes">
+    | Service | What you can do |
+    |---------|----------------|
+    | **LinkedIn** | Post updates, manage connections |
+    | **YouTube** | Access video info and transcripts |
+    | **WordPress** | Manage websites and blog content |
+  </Accordion>
+</AccordionGroup>
+
+---
+
+## Demo Videos
+
+### Agentic coding workflow
+[![Frontend dev demo](https://img.youtube.com/vi/vcSxzIIkg_0/0.jpg)](https://youtu.be/vcSxzIIkg_0)
+
+### Browser automation with Claude Code
+[![Agentic tasks demo](https://img.youtube.com/vi/rPFx_Btajj0/0.jpg)](https://youtu.be/rPFx_Btajj0)

docs/features/vertical-tabs.mdx

@@ -0,0 +1,60 @@
+---
+title: "Vertical Tabs"
+description: "Move your tabs to the side for a cleaner, more organized browsing experience"
+---
+
+BrowserOS supports vertical tabs — a side panel that lists all your open tabs along the left edge of the browser window. Instead of shrinking tab titles into a cramped horizontal strip, vertical tabs give each tab its own full-width row so you can read titles at a glance, even with dozens of tabs open.
+
+## Why Vertical Tabs?
+
+Modern screens are wide, not tall. A horizontal tab bar wastes vertical space you could use for content, and tabs quickly become unreadable as they shrink. Vertical tabs solve both problems:
+
+<CardGroup cols={2}>
+  <Card title="Read every tab title" icon="text">
+    Tabs stack vertically with full-width labels, so you always know what is open — no squinting at favicons.
+  </Card>
+  <Card title="Handle many tabs" icon="layer-group">
+    Open 30, 50, or 100 tabs without the strip becoming unusable. The side panel scrolls naturally.
+  </Card>
+  <Card title="Reclaim vertical space" icon="arrows-left-right">
+    The horizontal tab bar disappears, giving web pages more room on widescreen monitors.
+  </Card>
+  <Card title="Stay organized" icon="folder-tree">
+    Combine vertical tabs with tab groups to visually separate work, research, and personal browsing.
+  </Card>
+</CardGroup>
+
+## Enabling Vertical Tabs
+
+Toggle vertical tabs on or off from the Customization settings page.
+
+<Steps>
+  <Step title="Open Settings">
+    Go to `chrome://browseros/settings` in the address bar.
+  </Step>
+  <Step title="Go to Customization">
+    In the left sidebar, select **Customization**.
+  </Step>
+  <Step title="Toggle Use Vertical Tabs">
+    Flip the **Use Vertical Tabs** switch to on. The browser immediately moves your tabs to a side panel.
+  </Step>
+</Steps>
+
+<Frame caption="Enable vertical tabs in Settings > Customization">
+  <img src="/images/features--vertical-tabs-setting.png" alt="Vertical tabs toggle in BrowserOS Customization settings" />
+</Frame>
+
+To switch back, return to the same setting and turn the toggle off. Your tabs move back to the horizontal strip instantly.
+
+## How It Works
+
+When vertical tabs are enabled, the tab strip relocates from the top of the window to a collapsible side panel on the left. Each tab is displayed as a row showing the page favicon and full title.
+
+- **Click** a tab row to switch to it.
+- **Right-click** a tab for the standard context menu (pin, mute, close, move to group).
+- **Drag** tabs up or down to reorder them, or drag them into and out of tab groups.
+- The panel can be **collapsed** to show only favicons, freeing up even more horizontal space.
+
+## Vertical Tabs + Tab Groups
+
+Vertical tabs pair naturally with [tab groups](/features/workflows). Groups appear as collapsible sections in the side panel, making it easy to keep projects separate and fold away tabs you are not actively using.

docs/features/workflows.mdx

@@ -0,0 +1,69 @@
+---
+title: "Workflows"
+description: "Build reliable, repeatable browser automations with a visual graph builder"
+---
+
+Workflows let you turn complex browser tasks into reliable, reusable automations. Instead of hoping the agent figures out the right steps each time, you define the exact sequence—and run it whenever you need.
+
+See how to build and run a workflow end-to-end:
+
+<video
+  controls
+  className="w-full aspect-video rounded-xl"
+  src="https://pub-80f8a01e6e8b4239ae53a7652ef85877.r2.dev/resources/feature-videos/6-workflows.mp4"
+></video>
+
+## When to Use Workflows
+
+Use workflows when:
+- **Reliability matters** — The task needs to work the same way every time
+- **Steps are complex** — Multiple pages, loops, conditionals, or parallel actions
+- **You'll repeat it** — Run the same automation daily, weekly, or on-demand
+
+For quick, one-off tasks, the regular agent works well. For serious automation, build a workflow.
+
+## Creating Your First Workflow
+
+<img src="/features/workflow/workflows-page.png" alt="Access Workflows from the sidebar or create a new workflow" />
+
+1. Open the **Workflows** page from the sidebar
+2. Click **+ New Workflow**
+3. Describe what you want in the chat panel
+
+Try this example—copy and paste it to create a workflow that fills out forms from spreadsheet data:
+
+```
+Navigate to the spreadsheet https://dub.sh/browseros/test-spreadsheet. Get the contact information and fill it out in the form https://dub.sh/browseros/test-form for each entry in the spreadsheet. Feel free to parallelize this, but ensure all entries are filled.
+```
+
+The workflow agent will generate a visual graph representing each step. You can refine the workflow by chatting further—ask it to add steps, handle edge cases, or adjust the logic.
+
+<img src="/features/workflow/sample-workflow.png" alt="Generated workflow graph with parallel execution" />
+
+4. Click **Test Workflow** to run it and verify it works
+5. Click **Save Changes** to keep it for later
+
+## Running Workflows
+
+From the Workflows page, you can:
+- **Run** — Execute the workflow immediately
+- **Edit** — Open the graph builder to refine steps
+- **Delete** — Remove workflows you no longer need
+
+## Example Use Cases
+
+**Data entry automation**
+> Read contacts from a Google Sheet and submit each one to a web form—automatically handling pagination and parallel submissions.
+
+**LinkedIn outreach**
+> Visit each profile from a list, check if they match your criteria, and send a personalized connection request.
+
+**Price monitoring**
+> Check prices across multiple e-commerce sites, extract the data, and compile it into a spreadsheet.
+
+**Bulk unsubscribes**
+> Go through your Gmail, find subscription emails, and click unsubscribe on each one.
+
+## Feedback
+
+Workflows is a new feature. If you'd like to see scheduling support, sharing, or other capabilities, [open a GitHub issue](https://github.com/browseros-ai/BrowserOS/issues) with your request.

docs/images/icons/githubcopilot.svg

@@ -0,0 +1 @@
+<svg fill="currentColor" fill-rule="evenodd" height="1em" style="flex:none;line-height:1" viewBox="0 0 24 24" width="1em" xmlns="http://www.w3.org/2000/svg"><title>GithubCopilot</title><path d="M19.245 5.364c1.322 1.36 1.877 3.216 2.11 5.817.622 0 1.2.135 1.592.654l.73.964c.21.278.323.61.323.955v2.62c0 .339-.173.669-.453.868C20.239 19.602 16.157 21.5 12 21.5c-4.6 0-9.205-2.583-11.547-4.258-.28-.2-.452-.53-.453-.868v-2.62c0-.345.113-.679.321-.956l.73-.963c.392-.517.974-.654 1.593-.654l.029-.297c.25-2.446.81-4.213 2.082-5.52 2.461-2.54 5.71-2.851 7.146-2.864h.198c1.436.013 4.685.323 7.146 2.864zm-7.244 4.328c-.284 0-.613.016-.962.05-.123.447-.305.85-.57 1.108-1.05 1.023-2.316 1.18-2.994 1.18-.638 0-1.306-.13-1.851-.464-.516.165-1.012.403-1.044.996a65.882 65.882 0 00-.063 2.884l-.002.48c-.002.563-.005 1.126-.013 1.69.002.326.204.63.51.765 2.482 1.102 4.83 1.657 6.99 1.657 2.156 0 4.504-.555 6.985-1.657a.854.854 0 00.51-.766c.03-1.682.006-3.372-.076-5.053-.031-.596-.528-.83-1.046-.996-.546.333-1.212.464-1.85.464-.677 0-1.942-.157-2.993-1.18-.266-.258-.447-.661-.57-1.108-.32-.032-.64-.049-.96-.05zm-2.525 4.013c.539 0 .976.426.976.95v1.753c0 .525-.437.95-.976.95a.964.964 0 01-.976-.95v-1.752c0-.525.437-.951.976-.951zm5 0c.539 0 .976.426.976.95v1.753c0 .525-.437.95-.976.95a.964.964 0 01-.976-.95v-1.752c0-.525.437-.951.976-.951zM7.635 5.087c-1.05.102-1.935.438-2.385.906-.975 1.037-.765 3.668-.21 4.224.405.394 1.17.657 1.995.657h.09c.649-.013 1.785-.176 2.73-1.11.435-.41.705-1.433.675-2.47-.03-.834-.27-1.52-.63-1.813-.39-.336-1.275-.482-2.265-.394zm6.465.394c-.36.292-.6.98-.63 1.813-.03 1.037.24 2.06.675 2.47.968.957 2.136 1.104 2.776 1.11h.044c.825 0 1.59-.263 1.995-.657.555-.556.765-3.187-.21-4.224-.45-.468-1.335-.804-2.385-.906-.99-.088-1.875.058-2.265.394zM12 7.615c-.24 0-.525.015-.84.044.03.16.045.336.06.526l-.001.159a2.94 2.94 0 01-.014.25c.225-.022.425-.027.612-.028h.366c.187 0 .387.006.612.028-.015-.146-.015-.277-.015-.409.015-.19.03-.365.06-.526a9.29 9.29 0 00-.84-.044z"></path></svg>