feat: add eval framework and coordinate-based input tools

- Add hover_at, type_at, drag_at coordinate tools to server
- Add hoverAt, typeAt, dragAt methods to Browser class
- Export server internals (browser, tool-loop, registry) for eval imports
- Copy eval app from enterprise repo with agents, graders, runner, dashboard
- Nest eval-targets inside apps/eval
- Adapt sessionExecutionDir → workingDir for current server API
- Add biome ignore for dashboard HTML to prevent lint breaking onclick handlers

.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

@@ -0,0 +1,7 @@
+[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]
+llm-sync = "rsync -au .llm/ {{ repo_root }}/.llm/ 2>/dev/null || true"

.gitattributes

@@ -1,4 +1,12 @@
-resources/ filter=lfs diff=lfs merge=lfs -text
+resources/media/nxtscape-productivity.gif filter=lfs diff=lfs merge=lfs -text
 resources/nxtscape-productivity.gif filter=lfs diff=lfs merge=lfs -text
-docs/images/** 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
+# 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
 docs/videos/** filter=lfs diff=lfs merge=lfs -text

.github/ISSUE_TEMPLATE/01-bug.yml

@@ -0,0 +1,75 @@
+name: Bug report
+description: File a bug report for BrowserOS
+title: "<short description of the bug>"
+labels:
+  - "bug"
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thank you for taking the time to report this issue and help improve BrowserOS. We'll look into it! 🐛
+
+  - id: issue-type
+    type: dropdown
+    attributes:
+      label: Issue Type
+      description: What type of issue are you reporting?
+      options:
+        - Agent Issue
+        - Browser Issue
+        - Both / Not sure
+    validations:
+      required: true
+
+  - id: operating-system
+    type: dropdown
+    attributes:
+      label: Operating System
+      description: What operating system are you running?
+      options:
+        - macOS
+        - Windows
+        - Linux
+    validations:
+      required: true
+
+  - id: description
+    type: textarea
+    attributes:
+      label: Description of the bug
+      description: What happened and what did you expect?
+      placeholder: Describe what went wrong and what you expected to happen instead.
+    validations:
+      required: true
+
+  - id: reproduce
+    type: textarea
+    attributes:
+      label: Steps to Reproduce
+      placeholder: |
+        1. Open BrowserOS and navigate to...
+        2. Click on...
+        3. See error
+    validations:
+      required: true
+
+  - id: screenshots
+    type: textarea
+    attributes:
+      label: Screenshots / Videos
+      description: If applicable, add screenshots or videos to help explain your problem
+      placeholder: Drag and drop images/videos here or paste URLs
+
+  - id: browseros-version
+    type: input
+    attributes:
+      label: BrowserOS Version
+      description: Which version of BrowserOS are you using? (Find it in `chrome://settings/help`)
+      placeholder: e.g., 137.0.7212.69
+
+  - id: additional-context
+    type: textarea
+    attributes:
+      label: Additional Context
+      description: Add any other context about the problem here (logs, error messages, etc.)
+      placeholder: Paste error messages, logs, or any other relevant information...

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,14 @@
+blank_issues_enabled: false
+contact_links:
+  - name: 💬 Discord
+    url: https://discord.gg/YKwjt5vuKr
+    about: Join our Discord for help and discussions!
+  - name: 💼 Slack
+    url: https://dub.sh/browserOS-slack
+    about: Join our Slack for help and queries!
+  - name: 💡 Feature Requests
+    url: https://github.com/browseros-ai/BrowserOS/issues/99
+    about: Have an idea? Share it here and vote on others
+  - name: 📚 Documentation
+    url: https://docs.browseros.com/
+    about: Find setup guides and learn how to use BrowserOS

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,22 @@
+---
+name: Feature request
+about: Suggest a new feature or enhancement for BrowserOS
+title: '[Feature Request] '
+labels: enhancement
+assignees: ''
+---
+
+What problem does this solve? (describe the problem you're experiencing)
+* 
+
+How are you working around this today? (your current solution or workaround)
+* 
+
+What's your proposed solution? (how should BrowserOS address this?)
+* 
+
+Additional context (optional - add screenshots, examples, or other helpful details)
+* 
+
+---
+Thanks for sharing your idea! We love hearing how we can make BrowserOS better. ✨

.github/SECURITY.md

@@ -0,0 +1,19 @@
+## Reporting Security Issues
+
+If you believe you have found a security vulnerability in BrowserOS, please report it through coordinated disclosure.
+
+**Please do not report security vulnerabilities through the repository issues, discussions, or pull requests.**
+
+Instead, please open a new [Github security advisory](https://github.com/browseros-ai/BrowserOS/security/advisories/new).
+
+Please include as much of the information listed below as you can to help me better understand and resolve the issue:
+
+* The type of issue (e.g., buffer overflow, SQL injection, or cross-site scripting)
+* Full paths of source file(s) related to the manifestation of the issue
+* The location of the affected source code (tag/branch/commit or direct URL)
+* Any special configuration required to reproduce the issue
+* Step-by-step instructions to reproduce the issue
+* Proof-of-concept or exploit code (if possible)
+* Impact of the issue, including how an attacker might exploit the issue
+
+This information will help us triage your report more quickly.

.github/workflows/cla.yml

@@ -0,0 +1,59 @@
+name: 'CLA Assistant'
+on:
+  issue_comment:
+    types: [created]
+  pull_request_target:
+    types: [opened, closed, synchronize]
+
+# Explicitly configure permissions
+permissions:
+  actions: write
+  contents: write
+  pull-requests: write
+  statuses: write
+
+jobs:
+  CLAAssistant:
+    runs-on: ubuntu-latest
+    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'
+        uses: contributor-assistant/github-action@v2.6.1
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_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)
+          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
+          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.
+
+            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 comment on this PR with:**
+            `I have read the CLA Document and I hereby sign the CLA`
+
+          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'

.github/workflows/top-issues.yml

@@ -0,0 +1,115 @@
+name: Top Issues and Features by Votes
+
+on:
+  schedule:
+    - cron: "0 * * * *"  # Run every hour
+  workflow_dispatch:  # Allow manual triggering
+
+permissions:
+  issues: write
+  contents: read
+
+jobs:
+  update-top-issues:
+    runs-on: ubuntu-latest
+    if: github.repository == 'browseros-ai/BrowserOS'
+
+    steps:
+      - name: Update top issues list
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          ISSUE_NUMBER: 169
+        run: |
+          #!/bin/bash
+          set -e
+
+          echo "Fetching all open issues..."
+
+          # Fetch all open issues with reaction data
+          issues=$(gh api graphql -f query='
+            query($owner: String!, $repo: String!) {
+              repository(owner: $owner, name: $repo) {
+                issues(first: 100, states: OPEN, orderBy: {field: CREATED_AT, direction: DESC}) {
+                  nodes {
+                    number
+                    title
+                    url
+                    reactions(content: THUMBS_UP) {
+                      totalCount
+                    }
+                  }
+                }
+              }
+            }
+          ' -f owner='browseros-ai' -f repo='BrowserOS')
+
+          # 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) and (.title | contains("[RFC]"))))
+            | sort_by(-.reactions.totalCount)
+            | to_entries
+            | 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")
+          ')
+
+          # Create issue body
+          current_time=$(date -u +"%Y-%m-%d %H:%M:%S UTC")
+
+          {
+            echo "# Community Roadmap"
+            echo ""
+            echo "This list is automatically updated every hour based on 👍 reactions."
+            echo ""
+            echo "## How to Vote"
+            echo ""
+            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 "**Last updated:** $current_time"
+            echo ""
+            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 ""
+            echo "---"
+            echo "🤖 *This issue is automatically updated by [GitHub Actions](.github/workflows/top-issues.yml)*"
+          } > /tmp/issue_body.md
+
+          # Update the tracking issue
+          echo "Updating issue #$ISSUE_NUMBER..."
+          gh issue edit "$ISSUE_NUMBER" \
+            --repo browseros-ai/BrowserOS \
+            --body-file /tmp/issue_body.md
+
+          echo "✅ Successfully updated top issues list!"

.gitignore

@@ -1,8 +1,28 @@
 **/.DS_Store
 .gcs_entries
-build/
-dmg/
-scripts/__pycache__/
-scripts/patches/__pycache__/
-releases/
-.vscode/
+**/dmg
+**/env
+**/logs
+**/old-scripts
+
+# Python
+**/__pycache__/
+**/*.pyc
+**/*.pyo
+**/*.egg-info/
+**/*.egg
+**/.pytest_cache/
+**/dist/
+**/releases/
+**/.wrangler/
+**/node_modules/
+
+
+
+nxtscape-cli-access.json
+gclient.json
+.env
+.grove/
+**/resources/binaries/
+
+packages/browseros/build/tools/

CLA.md

@@ -0,0 +1,48 @@
+# BrowserOS Contributor License Agreement
+
+Thank you for your interest in contributing to BrowserOS ("we" or "us").
+
+This contributor agreement ("Agreement") documents the rights granted by contributors to Us. To make this document effective, please sign it and send it to us electronically following the instructions at the bottom of this document. This is a legally binding document, so please read it carefully before agreeing to it. The Agreement may cover more than one software project managed by Us.
+
+## 1. Definitions
+
+"You" (or "Your") shall mean the copyright owner or legal entity authorized by the copyright owner that is making this Agreement with Us. For legal entities, the entity making a Contribution and all other entities that control, are controlled by, or are under common control with that entity are considered to be a single Contributor. For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity.
+
+"Contribution" shall mean any original work of authorship, including any modifications or additions to an existing work, that is intentionally submitted by You to Us for inclusion in, or documentation of, any of the products owned or managed by Us (the "Work"). For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication sent to Us or our representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, Us for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by You as "Not a Contribution."
+
+## 2. Grant of Copyright License
+
+Subject to the terms and conditions of this Agreement, You hereby grant to Us and to recipients of software distributed by Us a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of Your Contributions, and to permit persons to whom the software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the software.
+
+## 3. Grant of Patent License
+
+Subject to the terms and conditions of this Agreement, You hereby grant to Us and to recipients of software distributed by Us a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by You that are necessarily infringed by Your Contribution(s) alone or by combination of Your Contribution(s) with the Work to which such Contribution(s) was submitted.
+
+## 4. AGPL-3.0 License Compliance
+
+You understand and agree that BrowserOS is licensed under the GNU Affero General Public License version 3.0 (AGPL-3.0). By making a Contribution, You acknowledge that:
+
+- You have read and understood the AGPL-3.0 license terms
+- Your Contribution will be made available under the AGPL-3.0 license
+- You agree to comply with all obligations under the AGPL-3.0 license for any use of the software
+- You understand that the AGPL-3.0 requires that any modified version used to provide a service over a network must make the complete source code available
+
+## 5. Representations
+
+You represent that:
+
+- You are legally entitled to grant the above licenses
+- Each of Your Contributions is Your original creation
+- Your Contribution submissions include complete details of any third-party license or other restriction (including related patents and trademarks) of which you are personally aware and which are associated with any part of Your Contributions
+
+## 6. Support
+
+You are not expected to provide support for Your Contributions, except to the extent You desire to provide support. You may provide support for free, for a fee, or not at all. Unless required by applicable law or agreed to in writing, You provide Your Contributions on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE.
+
+---
+
+**To sign this CLA, please comment on your pull request with:**
+
+I have read the CLA Document and I hereby sign the CLA

CLAUDE.md

@@ -0,0 +1,11 @@
+# Project Instructions
+
+## Docs Image Workflow
+
+When updating documentation that involves new screenshots or images:
+
+1. Prompt the user to copy the image to their clipboard (Cmd+C)
+2. Run: `python scripts/save_clipboard.py <target_path>`
+3. Example: `python scripts/save_clipboard.py docs/images/agent-step.png`
+
+This saves the clipboard image directly to the docs folder without manual file management.

CONTRIBUTING.md

@@ -0,0 +1,283 @@
+# 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 is a monorepo with two main parts:
+- **Agent** - The Chrome extension with AI features (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.
+
+## Pick Your Path
+
+<table>
+<tr>
+<td width="50%">
+
+### 🤖 Agent Development
+
+**What you'll work on:**
+- AI agent features & tools
+- UI/UX improvements
+- Browser automation
+- Testing & docs
+
+**What you need:**
+- Node.js 18+
+- ~500MB disk space
+- 10 minutes to set up
+
+**Skills:** TypeScript, React, Chrome APIs
+
+**[→ Agent Setup](#agent-development)**
+
+</td>
+<td width="50%">
+
+### 🌐 Browser Development
+
+**What you'll work on:**
+- Chromium patches
+- Build system
+- Platform features
+- Core browser stuff
+
+**What you need:**
+- ~100GB disk space
+- 16GB+ RAM (recommended)
+- 3+ hours for first build
+
+**Skills:** C++, Python, Chromium internals
+
+**[→ Browser Setup](#browser-development)**
+
+</td>
+</tr>
+</table>
+
+## Agent Development
+
+The agent is a Chrome extension that provides AI-powered automation. Most contributors work here.
+
+### Quick Setup
+
+```bash
+# 1. Navigate to agent directory
+cd packages/browseros-agent
+
+# 2. Install dependencies
+yarn install
+
+# 3. Set up environment
+cp .env.example .env
+# Edit .env and add your LITELLM_API_KEY
+
+# 4. Build the extension
+yarn build:dev       # One-time build
+```
+
+### Load in BrowserOS 
+
+1. Open `chrome://extensions/`
+2. Enable **Developer mode** (top right toggle)
+3. Click **Load unpacked**
+4. Select `packages/browseros-agent/dist/`
+5. Press Agent icon from extensions toolbar to open the agent panel
+
+**For detailed setup, architecture, and code standards, see [Agent Contributing Guide](packages/browseros-agent/CONTRIBUTING.md).**
+
+## 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.
+
+### Prerequisites
+
+- **~100GB disk space** for Chromium source
+- **16GB+ RAM** (recommended)
+- **Platform tools:**
+  - macOS: Xcode + Command Line Tools
+  - Linux: build-essential and dependencies
+  - Windows: Visual Studio Build Tools
+
+### Quick Setup
+
+**1. Checkout Chromium source**
+
+First, follow the official Chromium guide for your platform:
+- **[Chromium: Get the Code](https://www.chromium.org/developers/how-tos/get-the-code/)**
+
+This will set up `depot_tools` and fetch the ~100GB Chromium source tree. This typically takes 2-3 hours depending on your internet speed.
+
+**2. Build BrowserOS**
+
+Once you have Chromium checked out, navigate to our build system:
+
+```bash
+cd packages/browseros
+
+# Debug build (for development)
+# macOS
+python build/build.py --config build/config/debug.macos.yaml --chromium-src /path/to/chromium/src --build
+
+# Linux
+python build/build.py --config build/config/debug.linux.yaml --chromium-src /path/to/chromium/src --build
+
+# Windows
+python build/build.py --config build/config/debug.windows.yaml --chromium-src /path/to/chromium/src --build
+
+# Release build (for production)
+# macOS
+python build/build.py --config build/config/release.macos.yaml --chromium-src /path/to/chromium/src --build
+
+# Linux
+python build/build.py --config build/config/release.linux.yaml --chromium-src /path/to/chromium/src --build
+
+# Windows
+python build/build.py --config build/config/release.windows.yaml --chromium-src /path/to/chromium/src --build
+```
+
+The build typically takes 1-3 hours on modern hardware (M4 Max, Ryzen 9, etc.).
+
+**For detailed instructions, see [Browser Build Guide](docs/BUILD.md).**
+
+## 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:
+
+1. Read the [CLA document](CLA.md)
+2. Comment on your PR: `I have read the CLA Document and I hereby sign the CLA`
+3. The bot will record your signature (one-time thing)
+
+## 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
+
+- Keep functions short (<20 lines ideally)
+- Write tests for new features
+- Use descriptive variable names
+- Handle errors gracefully
+
+**For detailed standards:**
+- Agent: [packages/browseros-agent/CLAUDE.md](packages/browseros-agent/CLAUDE.md)
+- Browser: Follow Chromium style guide
+
+## 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            # This file
+```
+
+## Ways to Contribute
+
+You don't need to write code to help out! Here are other ways:
+
+### 🐛 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)
+
+### 💡 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).
+
+### 📚 Improve Documentation
+
+- Write blog posts or guides
+
+### 🧪 Test & Provide Feedback
+
+- Try new features
+- Test on different platforms
+- Report edge cases
+- Share your use cases
+
+### 🎨 Design & UX
+
+- Suggest UI improvements
+- Create mockups
+- Improve accessibility
+- Enhance user experience
+
+## Getting Help
+
+Stuck? Need clarification? We're here to help.
+
+- **[Discord](https://discord.gg/YKwjt5vuKr)** - Real-time chat and support
+- **[GitHub Issues](https://github.com/browseros-ai/BrowserOS/issues)** - Bug reports and features
+- **[GitHub Discussions](https://github.com/browseros-ai/BrowserOS/discussions)** - General questions
+
+## Recognition
+
+We appreciate all contributors! You'll get:
+- Credits in release notes
+- Name in README
+
+## License
+
+By contributing, you agree that your contributions will be licensed under AGPL-3.0.
+
+---
+
+Built with ❤️ from San Francisco
+
+Questions? Hit us up on [Discord](https://discord.gg/YKwjt5vuKr) or [Twitter](https://twitter.com/browseros_ai).

LICENSE.ungoogled_chromium

@@ -0,0 +1,31 @@
+BSD 3-Clause License (only for ungoogled chromium patches)
+
+The following license governs all ungoogled-chromium patches located in packages/browseros/series_patches/windows/ungoogled-chromium and packages/browseros/series_patches/ungoogled-chromium.
+
+Copyright (c) 2015-2023, The ungoogled-chromium Authors
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

README.md

@@ -1,74 +1,91 @@
 <div align="center">
+<img width="693" height="379" alt="github-banner" src="https://github.com/user-attachments/assets/1e37941c-4dbc-4662-9c8c-3bbe9971301d" />
 
-# 
-<img src="https://storage.googleapis.com/nxtscape/resources/new-nxtscape-banner.png" alt="backed-by-yc" >
-
-### Your browser, with AI superpowers 🚀
-
+<br></br>
 [![Discord](https://img.shields.io/badge/Discord-Join%20us-blue)](https://discord.gg/YKwjt5vuKr)
-[![Twitter](https://img.shields.io/twitter/follow/nxtscape?style=social)](https://twitter.com/nxtscape)
+[![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)
-<a href="https://github.com/nxtscape/nxtscape/releases/download/v0.1.0/Nxtscape_v0.1.0.dmg">
-  <img src="https://img.shields.io/badge/Download-macOS-black?style=flat&logo=apple&logoColor=white" alt="Download for macOS" />
+<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)" />
+</a>
+<a href="https://files.browseros.com/download/BrowserOS_installer.exe">
+  <img src="https://img.shields.io/badge/Download-Windows-0078D4?style=flat&logo=windows&logoColor=white" alt="Download for Windows (beta)" />
+</a>
+<a href="https://files.browseros.com/download/BrowserOS.AppImage">
+  <img src="https://img.shields.io/badge/Download-Linux-FCC624?style=flat&logo=linux&logoColor=black" alt="Download for Linux (beta)" />
+</a>
+<a href="https://cdn.browseros.com/download/BrowserOS.deb">
+  <img src="https://img.shields.io/badge/Download-Debian-D70A53?style=flat&logo=debian&logoColor=white" alt="Download Debian package" />
 </a>
-
 <br />
-<img src="resources/backed-by-yc.png" alt="backed-by-yc" width="140px">
-
 </div>
 
-🌐 Nxtscape is an open-source agentic browser that runs AI agents locally. Your privacy-first alternative to Arc, Dia, and Perplexity Comet.
+##
+🌐 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) and help us build! Have feature requests? [Suggest anonymously here](https://dub.sh/nxtscape-feature-request).
+💡 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).
 
 ## Quick start
 
-1. [Download and install Nxtscape](https://bit.ly/4k0gjsD)
+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)
-3. Connect your AI provider (OpenAI, Anthropic, or local Ollama)
+
+3. Connect your AI provider — use Claude, OpenAI, Gemini, or local models via Ollama and LMStudio.
+
 4. Start automating!
 
-## What makes Nxtscape special
-
-<div align="center">
-<img src="resources/example-use-cases.png" alt="example-use-cases" width="85%">
-</div>
-
-## Features
-
-- 🏠 Feels like home - same familiar interface as Google Chrome, works with all your extensions
+## What makes BrowserOS special
+- 🏠 Feels like home — same Chrome interface, all your extensions just work
 - 🤖 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
-- 🤝 (coming soon) MCP store to one-click install popular MCPs and use them directly in the browser bar
-- 🛡️ (coming soon) Built-in AI ad blocker that works across more scenarios!  
+- 🔒 Privacy first — bring your own keys or run local models with Ollama. Your browsing history stays on your machine
+- 🤝 [BrowserOS as MCP server](https://docs.browseros.com/features/use-with-claude-code) — control the browser from `claude-code`, `gemini-cli`, or any MCP client (31 tools)
+- 🔄 [Workflows](https://docs.browseros.com/features/workflows) — build repeatable browser automations with a visual graph builder
+- 📂 [Cowork](https://docs.browseros.com/features/cowork) — combine browser automation with local file operations. Research the web, save reports to your folder
+- ⏰ [Scheduled Tasks](https://docs.browseros.com/features/scheduled-tasks) — run the agent on autopilot, daily or every few minutes
+- 💬 [LLM Hub](https://docs.browseros.com/features/llm-chat-hub) — compare Claude, ChatGPT, and Gemini side-by-side on any page
+- 🛡️ Built-in ad blocker — [10x more protection than Chrome](https://docs.browseros.com/features/ad-blocking) with uBlock Origin + Manifest V2 support
+- 🚀 100% open source under AGPL-3.0
 
 ## Demos
 
-### 🤖 AI Agents in Action ([watch video](https://storage.googleapis.com/felafax-public/nxtscape/nxtscape-agent-demo.mp4))
-<div align="center">
-<img src="resources/nxtscape-agent.gif" alt="AI Agents in Action" width="80%">
-</div>
+### 🤖 BrowserOS agent in action
+[![BrowserOS agent in action](docs/videos/browserOS-agent-in-action.gif)](https://www.youtube.com/watch?v=SoSFev5R5dI)
+<br/><br/>
 
-### 💬 Local AI Chat ([watch video](https://storage.googleapis.com/felafax-public/nxtscape/nxtscape-chat.mp4))
-<div align="center">
-<img src="resources/nxtscape-chat.gif" alt="Local AI Chat" width="80%">
-</div>
+### 🎇 Install [BrowserOS as MCP](https://docs.browseros.com/features/use-with-claude-code) and control it from `claude-code`
 
-### ⚡ Productivity Tools ([watch video](https://storage.googleapis.com/felafax-public/nxtscape/nxtscape-productivity.mp4))
-<div align="center">
-<img src="resources/nxtscape-productivity.gif" alt="Productivity" width="80%">
-</div>
+https://github.com/user-attachments/assets/c725d6df-1a0d-40eb-a125-ea009bf664dc
 
-## Why we're building this
+<br/><br/>
 
-For the first time since Netscape in 1994, it feels like we can reimagine browsers from scratch. We saw how Cursor gave developers a 10x productivity boost, yet browsers feel stuck in the past.
+### 💬 Use BrowserOS to chat
 
-You probably have 70+ tabs open right now. You're constantly fighting your browser instead of it helping you. Simple tasks like "order Tide Pods from my Amazon order history" should just work with AI agents. 
+https://github.com/user-attachments/assets/726803c5-8e36-420e-8694-c63a2607beca
 
-We believe AI agents should automate your work locally and securely, not send your data to some search or ad company.
+<br/><br/>
+
+### ⚡ Use BrowserOS to scrape data
+
+https://github.com/user-attachments/assets/9f038216-bc24-4555-abf1-af2adcb7ebc0
+
+<br/><br/>
+
+## Why We're Building BrowserOS
+
+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.
+
+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.
+
+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!
 
 ## How we compare
 
@@ -96,21 +113,55 @@ Many loved Arc, but it was closed source. When they abandoned users, there was n
 They're a search/ad company. Your browser history becomes their product. We keep everything local.
 </details>
 
+<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>
+
 ## Contributing
 
-We'd love your help making Nxtscape better!
+We'd love your help making BrowserOS better!
 
-- 🐛 [Report bugs](https://github.com/nxtscape/nxtscape/issues)
-- 💡 [Suggest features](https://dub.sh/nxtscape-feature-request)
+- 🐛 [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)
-- 🐦 [Follow on Twitter](https://twitter.com/nxtscape)
+- 🐦 [Follow on Twitter](https://x.com/browserOS_ai)
 
 ## License
 
-Nxtscape is open source under the [AGPL-3.0 license](LICENSE).
+BrowserOS is open source under the [AGPL-3.0 license](LICENSE).
 
----
+## 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.
+
+## Citation
+
+If you use BrowserOS in your research or project, please cite:
+
+```bibtex
+@software{browseros2025,
+  author = {Sonti, Nithin and Sonti, Nikhil and {BrowserOS-team}},
+  title = {BrowserOS: The open-source Agentic browser},
+  url = {https://github.com/browseros-ai/BrowserOS},
+  year = {2025},
+  publisher = {GitHub},
+  license = {AGPL-3.0},
+}
+```
+
+Copyright &copy; 2025 Felafax, Inc.
+
+## 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 ❤️ by the Nxtscape team. Inspired by <a href="https://github.com/browser-use/browser-use">browser-use</a>, <a href="https://github.com/browserbase/stagehand">Stagehand</a>, <a href="https://github.com/nanobrowser/nanobrowser">Nanobrowser</a> and of course only possible because of <a href="https://github.com/chromium/chromium">Chromium</a>.
+Built with ❤️ from San Francisco
 </p>
+
+

build.sh

@@ -1,250 +0,0 @@
-#!/usr/bin/env bash
-
-# ==========================================================================
-# NXTscape Browser Build Script
-# ==========================================================================
-# Usage: ./build.sh [options] [architecture]
-#
-# Options:
-#   -r    Build release version (default is debug build)
-#   -n    Non-interactive mode (use all defaults, no prompts)
-#
-# Architecture:
-#   arm64  Build for Apple Silicon (default)
-#   x64    Build for Intel processors
-#
-# Examples:
-#   ./build.sh              # Debug build for arm64
-#   ./build.sh -r           # Release build for arm64
-#   ./build.sh x64          # Debug build for x64
-#   ./build.sh -r x64       # Release build for x64
-#   ./build.sh -n           # Debug build with all defaults (no prompts)
-#   ./build.sh -nr          # Release build with all defaults (no prompts)
-# ==========================================================================
-
-# Exit immediately if a command fails (e), treat unset variables as errors (u),
-# and print commands before execution (x)
-set -eux
-
-# Build script for local macOS environment
-
-# Some path variables
-_root_dir=$(dirname $(greadlink -f $0)) # Gets the absolute path of the script directory
-_src_dir="$_root_dir/build/src/"        # Chromium source code directory
-_out_dir="Default"
-
-chromium_version=$(cat "$_root_dir/scripts/chromium_version.txt")
-
-# Function to copy icons from resources to the Chromium theme directory
-copy_icons() {
-  local src_dir="$1"
-  local chromium_theme_dir="$2"
-
-  echo "Copying icon files to Chromium theme directory: $chromium_theme_dir"
-
-  if [ -d "$src_dir" ]; then
-    # Main PNG files
-    echo "Copying PNG files..."
-    cp -f "$src_dir/"*.png "$chromium_theme_dir/"
-
-    # SVG and AI files
-    echo "Copying SVG and AI files..."
-    cp -f "$src_dir/"*.svg "$chromium_theme_dir/"
-    cp -f "$src_dir/"*.ai "$chromium_theme_dir/"
-
-    # Copy subdirectories
-    echo "Copying platform-specific icons..."
-
-    # Mac icons
-    if [ -d "$src_dir/mac" ]; then
-      mkdir -p "$chromium_theme_dir/mac"
-      cp -f "$src_dir/mac/"* "$chromium_theme_dir/mac/"
-    fi
-
-    # Windows icons
-    if [ -d "$src_dir/win" ]; then
-      mkdir -p "$chromium_theme_dir/win"
-      cp -rf "$src_dir/win/"* "$chromium_theme_dir/win/"
-    fi
-
-    # Linux icons
-    if [ -d "$src_dir/linux" ]; then
-      mkdir -p "$chromium_theme_dir/linux"
-      cp -f "$src_dir/linux/"* "$chromium_theme_dir/linux/"
-    fi
-
-    # ChromeOS icons
-    if [ -d "$src_dir/chromeos" ]; then
-      mkdir -p "$chromium_theme_dir/chromeos"
-      cp -f "$src_dir/chromeos/"* "$chromium_theme_dir/chromeos/"
-    fi
-
-    echo "Icon files copied successfully."
-  else
-    echo "Warning: Icon source directory $src_dir not found. Skipping icon copy step."
-  fi
-}
-
-# Parse command line options
-release=false         # Default is debug build
-non_interactive=false # Default is interactive mode
-while getopts 'rn' OPTION; do
-  case "$OPTION" in
-  r)
-    release=true # -r option enables release build
-    ;;
-  n)
-    non_interactive=true # -n option enables non-interactive mode
-    ;;
-  esac
-done
-
-shift "$(($OPTIND - 1))" # Shift positional parameters to access non-option arguments
-
-_arch=${1:-arm64} # Set build architecture, default to arm64 if not specified
-
-# Variables for build steps - will be prompted
-# Initialize to false so pressing Enter means "No"
-should_apply_patches=false
-should_sign_package=false
-should_clean_build=false
-should_reset_git=false
-should_clean_git=false
-
-if [ "$non_interactive" = true ]; then
-  should_apply_patches=true
-  should_sign_package=true
-  should_clean_build=true
-  should_reset_git=true
-  should_clean_git=true
-fi
-
-# Handle interactive vs non-interactive mode
-if [ "$non_interactive" = false ]; then
-  read -p "Clean previous build artifacts (out/ directory)? (y/N). Press enter for NO: " -r reply
-  if [[ "$reply" =~ ^[Yy]$ ]]; then
-    should_clean_build=true
-  fi
-  read -p "Apply patches? (y/N). Press enter for NO: " -r reply
-  if [[ "$reply" =~ ^[Yy]$ ]]; then
-    should_apply_patches=true
-  fi
-  read -p "Sign and package the application after build? (y/N). Press enter for NO: " -r reply
-  if [[ "$reply" =~ ^[Yy]$ ]]; then
-    should_sign_package=true
-  fi
-  read -p "Reset git branch and remove all tracked files? (y/N). Press enter for NO: " -r reply
-  if [[ "$reply" =~ ^[Yy]$ ]]; then
-    should_reset_git=true
-  fi
-else
-  echo "Running in non-interactive mode with default settings:"
-  echo "  - Clean build: $should_clean_build"
-  echo "  - Apply patches: $should_apply_patches"
-  echo "  - Sign package: $should_sign_package"
-  echo "  - Reset git: $should_reset_git"
-  echo "  - Clean git: $should_clean_git"
-fi
-
-# Reset git branch if requested
-if [ "$should_reset_git" = true ]; then
-  echo "Resetting git branch and removing all tracked files..."
-  cd "$_src_dir"
-  git reset --hard HEAD
-  cd "$_root_dir"
-fi
-
-# Clean git with exclusions for important directories
-if [ "$should_clean_git" = true ]; then
-  cd "$_src_dir"
-  echo "Running git clean with exclusions for gn and other important tools..."
-
-  # let's clean only in chrome
-  git clean -fdx chrome/ \
-    --exclude="third_party/" \
-    --exclude="build_tools/" \
-    --exclude="uc_staging/" \
-    --exclude="buildtools/" \
-    --exclude="tools/" \
-    --exclude="build/"
-  cd "$_root_dir"
-fi
-
-# Fetch tags and switch to Chromium version tag
-cd "$_src_dir"
-echo "Fetching tags and switching to Chromium version $chromium_version..."
-git fetch --tags
-git checkout tags/$chromium_version
-
-echo "Running gclient sync with minimal history..."
-# Use --no-history to skip git history and --shallow for minimal checkout
-# These reduce checkout size and time significantly
-gclient sync -D --no-history --shallow
-cd "$_root_dir"
-
-# Clean up previous build artifacts
-if [ "$should_clean_build" = true ]; then
-  echo "Cleaning up previous build artifacts..."
-  rm -rf "$_src_dir/out/$_out_dir" || true # Remove previous output directory
-fi
-
-# Create output directory
-mkdir -p "$_src_dir/out/$_out_dir"
-
-# Apply patches
-if [ "$should_apply_patches" = true ]; then
-  echo "Applying patches..."
-  python3 "$_root_dir/scripts/patches.py" apply "$_src_dir" "$_root_dir/patches"
-fi
-
-# Set build flags based on build type
-if [ "$release" = true ]; then
-  echo "Using release build configuration..."
-  cat "$_root_dir/scripts/flags.macos.release.gn" >"$_src_dir/out/$_out_dir/args.gn"
-else
-  echo "Using debug build configuration..."
-  cat "$_root_dir/scripts/flags.macos.debug.gn" >"$_src_dir/out/$_out_dir/args.gn"
-fi
-
-# Set target_cpu to the corresponding architecture
-if [[ $_arch == "arm64" ]]; then
-  echo 'target_cpu = "arm64"' >>"$_src_dir/out/$_out_dir/args.gn" # For ARM64/Apple Silicon
-else
-  echo 'target_cpu = "x64"' >>"$_src_dir/out/$_out_dir/args.gn" # For Intel x64
-fi
-
-# Copy over AI side panel resources
-_ai_side_panel_dir="$_src_dir/chrome/browser/resources/ai_side_panel"
-
-echo "Creating directory:"
-echo "  $_ai_side_panel_dir"
-
-mkdir -p "$_ai_side_panel_dir"
-
-echo "Copying content from felafax-chromium:"
-echo "  from: $_root_dir/files/ai_side_panel"
-echo "    to: $_ai_side_panel_dir"
-
-cp -r $_root_dir/files/ai_side_panel/* "$_ai_side_panel_dir"
-
-# Copy icons from resources/output to the Chromium theme directory
-_chromium_theme_dir="$_src_dir/chrome/app/theme/chromium"
-copy_icons "$_root_dir/resources/gen" "$_chromium_theme_dir"
-
-# Change to source directory for building
-cd "$_src_dir"
-
-# Generate ninja build files
-if [ "$should_clean_build" = true ]; then
-  echo "Generating ninja build files..."
-  gn gen out/$_out_dir --fail-on-unused-args
-fi
-
-# autoninja is a wrapper around ninja that automatically sets optimal parameters
-autoninja -C out/$_out_dir chrome chromedriver
-
-# Sign and package the application
-if [ "$should_sign_package" = true ]; then
-  echo "Signing and packaging the application..."
-  $_root_dir/sign_and_package_app.sh
-fi

docs/BUILD.md

@@ -1,74 +0,0 @@
-# Building Nxtscape
-
-This guide will walk you through building Nxtscape from source on macOS.
-
-## Prerequisites
-
-- macOS (tested on M4 Max)
-- Xcode and Command Line Tools
-- Python 3
-- Git
-- ~100GB of free disk space (for Chromium source)
-- ~8GB RAM minimum (16GB+ recommended)
-
-## Build Instructions
-
-### Step 1: Checkout Chromium
-
-First, you need to get the Chromium source code. Follow the official Chromium instructions:
-
-1. Visit the [Chromium Get the Code guide](https://www.chromium.org/developers/how-tos/get-the-code/)
-2. Follow the macOS-specific instructions to set up depot_tools and fetch Chromium
-3. Clone the Chromium repository into a `build` directory inside your nxtscape repository:
-
-```bash
-cd /path/to/nxtscape
-mkdir build
-cd build
-# Follow Chromium checkout instructions here
-```
-
-### Step 2: Apply Nxtscape Patches
-
-Once you have Chromium checked out, the Nxtscape patches need to be applied to customize the browser with AI features.
-
-### Step 3: Build Nxtscape
-
-Nxtscape provides a build script that handles the compilation process.
-
-#### For Debug Build:
-```bash
-./build.sh -n
-```
-**Note:** The build process typically takes around 3 hours on an M4 Max laptop. Build times may vary based on your hardware specifications.
-
-### Step 4: Run Nxtscape
-
-After the build completes successfully, you can run Nxtscape using:
-
-```bash
-out/Default/Nxtscape.app/Contents/MacOS/Nxtscape --use-mock-keychain
-```
-
-The `--use-mock-keychain` flag is used to avoid keychain permission prompts during development.
-
-## Troubleshooting
-
-### Common Issues
-
-1. **Build fails with missing dependencies**
-   - Make sure you've followed all prerequisite steps from the Chromium build guide
-   - Ensure Xcode is up to date
-
-2. **Out of disk space**
-   - Chromium requires significant disk space (~100GB)
-
-### Getting Help
-
-If you encounter issues:
-- Join our [Discord](https://discord.gg/YKwjt5vuKr) for community support
-- Check existing issues on GitHub
-- Review the Chromium build documentation for platform-specific troubleshooting
-
-
-Happy building! 🚀

docs/appcast.xml

@@ -1,33 +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>Nxtscape Browser</title>
-    <link>https://nxtscape.github.io/nxtscape/appcast.xml</link>
-    <description>Most recent changes with links to updates.</description>
-    <language>en</language>
-
-    <!-- Updates -->
-    <item>
-      <title>Nxtscape - 0.1.0</title>
-      <description>
-        <ul>
-          <li>Updates to AI agent to perform better on navigation tasks</li>
-          <li>Improves to MacOS updater</li>
-          <li>Fixing history import bug</li>
-        </ul>
-      </description>
-      <sparkle:version>7151.139</sparkle:version>
-      <sparkle:shortVersionString>0.1.0</sparkle:shortVersionString>
-      <pubDate>Mon, 23 Jun 2025 00:00:00 +0000</pubDate>
-      <link>https://nxtscape.ai</link>
-      <enclosure
-        url="https://storage.googleapis.com/nxtscape/Nxtscape_v0.1.0.dmg"
-        sparkle:edSignature="mPxpc/8SPEEOiCmiKE4haTGUaMRnUQRJ8SK8w3sWek/5oZD0dg/DQFg/HxbhHjt2mtFUI8VD5iUi4+uIBWr4Dg=="
-        length="127005947"
-        type="application/octet-stream" />
-      <sparkle:minimumSystemVersion>10.15</sparkle:minimumSystemVersion>
-    </item>
-
-  </channel>
-</rss>

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

@@ -0,0 +1,267 @@
+---
+title: "Contributing to BrowserOS"
+description: "Guide to contributing to BrowserOS"
+---
+
+BrowserOS has two main parts you can contribute to:
+
+- **Agent** — The AI features, UI, and browser automation (TypeScript/React)
+- **Browser** — The custom Chromium build (C++/Python)
+
+Most contributors work on the Agent since it's much easier to set up.
+
+## Quick Links
+
+- [GitHub Repository](https://github.com/BrowserOS-ai/BrowserOS)
+- [Discord Community](https://discord.gg/YKwjt5vuKr)
+- [Report Issues](https://github.com/BrowserOS-ai/BrowserOS/issues)
+
+## Ways to Contribute
+
+**Report bugs** — [Open an issue](https://github.com/browseros-ai/BrowserOS/issues/new) with steps to reproduce, expected vs actual behavior, and screenshots.
+
+**Suggest features** — Share ideas on [GitHub](https://github.com/browseros-ai/BrowserOS/issues/99) or [Discord](https://discord.gg/YKwjt5vuKr).
+
+**Improve docs** — Docs live in `docs/` and use Mintlify. Edit pages and update `docs/docs.json` for navigation.
+
+---
+
+## Path 1: Agent Development
+
+The Agent is a monorepo with 3 components:
+
+| 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 |
+
+### Architecture
+
+<img src="/images/contributing--architecture.png" alt="BrowserOS Agent architecture diagram" />
+
+### Setup
+
+```bash
+# Clone the repo
+git clone https://github.com/YOUR-USERNAME/BrowserOS.git
+cd BrowserOS/packages/browseros-agent
+
+# Install dependencies
+bun install
+
+# Copy environment files
+cp apps/server/.env.example apps/server/.env.development
+cp apps/agent/.env.example apps/agent/.env.development
+```
+
+### Running Locally
+
+```bash
+# Terminal 1: Start the server
+bun run start:server
+
+# Terminal 2: Start the agent extension (dev mode)
+bun run start:agent
+```
+
+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
+
+### Commands
+
+| 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 |
+
+---
+
+## Path 2: Browser Development
+
+Only go down this path if you're working on Chromium-level features like patches to the browser itself.
+
+**Requirements:**
+- ~100GB disk space
+- 16GB+ RAM recommended
+- 3+ hours for first build
+
+### Prerequisites
+
+<Tabs>
+  <Tab title="macOS">
+    - macOS with Xcode and Command Line Tools
+    - Python 3.12+
+    - [UV](https://docs.astral.sh/uv/) (Python package manager)
+    - Git
+  </Tab>
+  <Tab title="Linux">
+    - Ubuntu 20.04+ or similar
+    - build-essential package
+    - Python 3.12+
+    - [UV](https://docs.astral.sh/uv/)
+    - Git
+  </Tab>
+  <Tab title="Windows">
+    - Windows 10/11
+    - Visual Studio 2022 with C++ workload
+    - Python 3.12+
+    - [UV](https://docs.astral.sh/uv/)
+    - Git
+  </Tab>
+</Tabs>
+
+### Build Instructions
+
+**1. Clone Chromium source**
+
+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.
+
+Note the path where you clone it (e.g., `~/chromium/src`).
+
+**2. Install UV and 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
+    <chromium-src>/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
+    <chromium-src>/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
+    <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>
+
+### Build Flags
+
+| Flag | Description |
+|------|-------------|
+| `--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` | `debug` or `release` |
+| `--sign` | Sign the build |
+| `--package` | Package for distribution |
+
+### Troubleshooting
+
+**Build fails with missing dependencies** — Make sure you followed all steps from the Chromium build guide for your platform.
+
+**Out of disk space** — Chromium needs ~100GB. Check with `df -h`.
+
+**Build takes too long** — Use ccache, more CPU cores, or stick to debug builds.
+
+**UV command not found** — Restart your terminal after installing UV.
+
+---
+
+## 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

@@ -0,0 +1,105 @@
+{
+  "$schema": "https://mintlify.com/docs.json",
+  "theme": "maple",
+  "name": "BrowserOS Documentation",
+  "colors": {
+    "primary": "#f25e1a",
+    "light": "#FF7A3D",
+    "dark": "#D14E10"
+  },
+  "favicon": "/logo/favicon.png",
+  "navigation": {
+    "groups": [
+      {
+        "group": "Get Started",
+        "pages": [
+          "index",
+          "onboarding",
+          "update/index",
+          "changelog"
+        ]
+      },
+      {
+        "group": "Core Features",
+        "pages": [
+          "features/bring-your-own-llm",
+          "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",
+          "features/vertical-tabs"
+        ]
+      },
+      {
+        "group": "Comparisons",
+        "pages": [
+          "comparisons/chrome-devtools-mcp",
+          "comparisons/claude-cowork",
+          "comparisons/openclaw"
+        ]
+      },
+      {
+        "group": "Integrations",
+        "pages": ["integrations/n8n"]
+      },
+      {
+        "group": "Troubleshooting",
+        "pages": ["troubleshooting/connection-issues"]
+      },
+      {
+        "group": "Contributing",
+        "pages": ["contributing"]
+      }
+    ]
+  },
+  "logo": {
+    "light": "/logo/logo44.png",
+    "dark": "/logo/logo44.png"
+  },
+  "navbar": {
+    "links": [
+      {
+        "label": "llms.txt",
+        "href": "/llms.txt"
+      },
+      {
+        "label": "Support",
+        "href": "https://discord.gg/YKwjt5vuKr"
+      }
+    ],
+    "primary": {
+      "type": "button",
+      "label": "Download",
+      "href": "https://browseros.com"
+    }
+  },
+  "contextual": {
+    "options": [
+      "copy",
+      "view",
+      "chatgpt",
+      "claude",
+      "perplexity",
+      "mcp",
+      "cursor",
+      "vscode"
+    ]
+  },
+  "footer": {
+    "socials": {
+      "x": "https://x.com/browseros_ai",
+      "github": "https://github.com/BrowserOS-ai/BrowserOS",
+      "discord": "https://discord.gg/YKwjt5vuKr",
+      "slack": "https://dub.sh/browserOS-slack"
+    }
+  }
+}

docs/features/ad-blocking.mdx

@@ -0,0 +1,35 @@
+---
+title: "Ad Blocking"
+description: "BrowserOS supports full ad blocking with uBlock Origin"
+---
+
+BrowserOS supports full ad blocking through [uBlock Origin](https://ublockorigin.com/), the most effective open-source ad blocker available.
+
+## How It Works
+
+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. We re-enabled Manifest V2 support in BrowserOS so uBlock Origin can run at full power.
+
+Install it from the Chrome Web Store: [uBlock Origin](https://chromewebstore.google.com/detail/ublock-origin/cjpalhdlnbpafiamejdnhcphjbkeiagm)
+
+## BrowserOS vs Chrome
+
+We ran both browsers through [adblock.turtlecute.org](https://adblock.turtlecute.org/), a test that measures how effectively a browser blocks ads and tracking scripts.
+
+<CardGroup cols={2}>
+  <Card title="BrowserOS — 68%">
+    <img src="/images/adblock-browseros.png" alt="BrowserOS blocking 68% of ads" />
+  </Card>
+  <Card title="Chrome — 7%">
+    <img src="/images/adblock-chrome.png" alt="Chrome blocking only 7% of ads" />
+  </Card>
+</CardGroup>
+
+Out of 133 ad-related requests:
+- **BrowserOS** blocked 91 (68%)
+- **Chrome** blocked 9 (7%)
+
+That's roughly **10x more protection** with zero configuration.
+
+## What This Means
+
+Fewer ads means faster page loads, less bandwidth usage, and significantly reduced tracking. BrowserOS handles this natively so you can focus on browsing.

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

@@ -0,0 +1,257 @@
+---
+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>
+
+## 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/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/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/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.