V4 docs refactor (#322)

2025-12-12 04:15:30 +00:00 · 2025-06-01 18:51:12 -07:00 · 2025-06-01 18:51:12 -07:00 · ce8d55f558
commit ce8d55f558
parent a2e06266db
59 changed files with 617 additions and 536 deletions
--- a/.github/workflows/docs-broken-links.yml
+++ b/.github/workflows/docs-broken-links.yml
@ -0,0 +1,26 @@
 name: Check for broken links in docs
 on:
  pull_request:
    branches: ["main"]
    paths:
      - "docs/**"
 jobs:
  check-links:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
      - name: Use Node.Js
        uses: actions/setup-node@v4
        with:
            node-version: '20.x'
      - name: Install Mintlify CLI
        run: npm i -g mintlify
      - name: Check for broken links
        working-directory: docs
        run: mintlify broken-links
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@ -17,19 +17,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [4.0.0] - 2025-05-28
-Sourcebot V4 introduces authentication, performance improvements and code navigation. Checkout the [migration guide](https://docs.sourcebot.dev/self-hosting/upgrade/v3-to-v4-guide) for information on upgrading your instance to v4.
+Sourcebot V4 introduces authentication, performance improvements and code navigation. Checkout the [migration guide](https://docs.sourcebot.dev/docs/upgrade/v3-to-v4-guide) for information on upgrading your instance to v4.
 ### Changed
 - [**Breaking Change**] Authentication is now required by default. Notes:
  - When setting up your instance, email / password login will be the default authentication provider.
-  - The first user that logs into the instance is given the `owner` role. ([docs](https://docs.sourcebot.dev/docs/more/roles-and-permissions)).
+  - The first user that logs into the instance is given the `owner` role. ([docs](https://docs.sourcebot.dev/docs/configuration/auth/roles-and-permissions)).
  - Subsequent users can request to join the instance. The `owner` can approve / deny requests to join the instance via `Settings` > `Members` > `Pending Requests`.
  - If a user is approved to join the instance, they are given the `member` role.
-  - Additional login providers, including email links and SSO, can be configured with additional environment variables. ([docs](https://docs.sourcebot.dev/self-hosting/configuration/authentication)).
+  - Additional login providers, including email links and SSO, can be configured with additional environment variables. ([docs](https://docs.sourcebot.dev/docs/configuration/auth/overview)).
 - Clicking on a search result now takes you to the `/browse` view. Files can still be previewed by clicking the "Preview" button or holding `Cmd` / `Ctrl` when clicking on a search result. [#315](https://github.com/sourcebot-dev/sourcebot/pull/315)
 ### Added
- [Sourcebot EE] Added search-based code navigation, allowing you to jump between symbol definition and references when viewing source files. [Read the documentation](https://docs.sourcebot.dev/docs/search/code-navigation). [#315](https://github.com/sourcebot-dev/sourcebot/pull/315)
+- [Sourcebot EE] Added search-based code navigation, allowing you to jump between symbol definition and references when viewing source files. [Read the documentation](https://docs.sourcebot.dev/docs/features/code-navigation). [#315](https://github.com/sourcebot-dev/sourcebot/pull/315)
 - Added collapsible filter panel. [#315](https://github.com/sourcebot-dev/sourcebot/pull/315)
 - Added Sourcebot API key management for external clients. [#311](https://github.com/sourcebot-dev/sourcebot/pull/311)
@ -44,7 +44,7 @@ Sourcebot V4 introduces authentication, performance improvements and code naviga
 ## [3.2.0] - 2025-05-12
 ### Added
- Added AI code review agent [#298](https://github.com/sourcebot-dev/sourcebot/pull/298). Checkout the [docs](https://docs.sourcebot.dev/docs/agents/review-agent) for more information.
+- Added AI code review agent [#298](https://github.com/sourcebot-dev/sourcebot/pull/298). Checkout the [docs](https://docs.sourcebot.dev/docs/features/agents/review-agent) for more information.
 ### Fixed
 - Fixed issue with repos appearing in the carousel when they fail indexing for the first time. [#305](https://github.com/sourcebot-dev/sourcebot/pull/305)
@ -113,20 +113,20 @@ Sourcebot V4 introduces authentication, performance improvements and code naviga
 ## [3.0.0] - 2025-04-01
-Sourcebot v3 is here and brings a number of structural changes to the tool's foundation, including a SQL database, parallelized indexing, authentication support, multitenancy, and more. Checkout the [migration guide](https://docs.sourcebot.dev/self-hosting/upgrade/v2-to-v3-guide) for information on upgrading your instance to v3.
+Sourcebot v3 is here and brings a number of structural changes to the tool's foundation, including a SQL database, parallelized indexing, authentication support, multitenancy, and more. Checkout the [migration guide](https://docs.sourcebot.dev/docs/upgrade/v2-to-v3-guide) for information on upgrading your instance to v3.
 ### Changed
- [**Breaking Change**] Changed the config schema such that connection objects are specified in the `connection` map, instead of the `repos` array. [See migration guide](https://docs.sourcebot.dev/self-hosting/upgrade/v2-to-v3-guide).
+- [**Breaking Change**] Changed the config schema such that connection objects are specified in the `connection` map, instead of the `repos` array. [See migration guide](https://docs.sourcebot.dev/docs/upgrade/v2-to-v3-guide).
 - Updated the tool's color-palette in dark mode.
 ### Added
- Added parallelized repo indexing and connection syncing via Redis & BullMQ. See the [architecture overview](https://docs.sourcebot.dev/self-hosting/overview#architecture).
+- Added parallelized repo indexing and connection syncing via Redis & BullMQ. See the [architecture overview](https://docs.sourcebot.dev/docs/overview#architecture).
 - Added repo indexing progress indicators in the navbar.
- Added authentication support via OAuth or email/password. For instructions on enabling, see [this doc](https://docs.sourcebot.dev/self-hosting/configuration/authentication).
+- Added authentication support via OAuth or email/password. For instructions on enabling, see [this doc](https://docs.sourcebot.dev/docs/configuration/auth/overview).
- Added the following UI for managing your deployment when **[auth is enabled](https://docs.sourcebot.dev/self-hosting/configuration/authentication)**:
+- Added the following UI for managing your deployment when **[auth is enabled](https://docs.sourcebot.dev/docs/configuration/auth/overview)**:
  - connection management: create and manage your JSON configs via a integrated web-editor.
  - secrets: import personal access tokens (PAT) into Sourcebot (AES-256 encrypted). Reference secrets in your connection config by name.
-  - team & invite management: invite users to your instance to give them access. Configure team [roles & permissions](https://docs.sourcebot.dev/docs/more/roles-and-permissions).
+  - team & invite management: invite users to your instance to give them access. Configure team [roles & permissions](https://docs.sourcebot.dev/docs/configuration/auth/roles-and-permissions).
 - Added multi-tenancy support. See [this doc](https://docs.sourcebot.dev/self-hosting/more/tenancy).
 ### Removed
--- a/docs/development.mdx
+++ b/docs/development.mdx
@ -1,107 +0,0 @@
 ---
 title: 'Development'
 description: 'Preview changes locally to update your docs'
 ---
 <Info>
  **Prerequisite**: Please install Node.js (version 19 or higher) before proceeding. <br />
  Please upgrade to ```docs.json``` before proceeding and delete the legacy ```mint.json``` file.
 </Info>
 Follow these steps to install and run Mintlify on your operating system:
 **Step 1**: Install Mintlify:
 <CodeGroup>
  ```bash npm
  npm i -g mintlify
  ```
 ```bash yarn
 yarn global add mintlify
 ```
 </CodeGroup>
 **Step 2**: Navigate to the docs directory (where the `docs.json` file is located) and execute the following command:
 ```bash
 mintlify dev
 ```
 A local preview of your documentation will be available at `http://localhost:3000`.
 ### Custom Ports
 By default, Mintlify uses port 3000. You can customize the port Mintlify runs on by using the `--port` flag. To run Mintlify on port 3333, for instance, use this command:
 ```bash
 mintlify dev --port 3333
 ```
 If you attempt to run Mintlify on a port that's already in use, it will use the next available port:
 ```md
 Port 3000 is already in use. Trying 3001 instead.
 ```
 ## Mintlify Versions
 Please note that each CLI release is associated with a specific version of Mintlify. If your local website doesn't align with the production version, please update the CLI:
 <CodeGroup>
 ```bash npm
 npm i -g mintlify@latest
 ```
 ```bash yarn
 yarn global upgrade mintlify
 ```
 </CodeGroup>
 ## Validating Links
 The CLI can assist with validating reference links made in your documentation. To identify any broken links, use the following command:
 ```bash
 mintlify broken-links
 ```
 ## Deployment
 <Tip>
  Unlimited editors available under the [Pro
  Plan](https://mintlify.com/pricing) and above.
 </Tip>
 If the deployment is successful, you should see the following:
 <Frame>
  <img src="/images/checks-passed.png" style={{ borderRadius: '0.5rem' }} />
 </Frame>
 ## Code Formatting
 We suggest using extensions on your IDE to recognize and format MDX. If you're a VSCode user, consider the [MDX VSCode extension](https://marketplace.visualstudio.com/items?itemName=unifiedjs.vscode-mdx) for syntax highlighting, and [Prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) for code formatting.
 ## Troubleshooting
 <AccordionGroup>
  <Accordion title='Error: Could not load the "sharp" module using the darwin-arm64 runtime'>
    This may be due to an outdated version of node. Try the following:
    1. Remove the currently-installed version of mintlify: `npm remove -g mintlify`
    2. Upgrade to Node v19 or higher.
    3. Reinstall mintlify: `npm install -g mintlify`
  </Accordion>
  <Accordion title="Issue: Encountering an unknown error">
    Solution: Go to the root of your device and delete the \~/.mintlify folder. Afterwards, run `mintlify dev` again.
  </Accordion>
 </AccordionGroup>
 Curious about what changed in the CLI version? [Check out the CLI changelog.](https://www.npmjs.com/package/mintlify?activeTab=versions)
--- a/docs/docs.json
+++ b/docs/docs.json
@ -1,6 +1,6 @@
 {
    "$schema": "https://mintlify.com/docs.json",
-    "theme": "mint",
+    "theme": "willow",
    "name": "Sourcebot",
    "colors": {
        "primary": "#851EE7",
@ -15,23 +15,45 @@
        "anchors": [
            {
                "anchor": "Docs",
-                "icon": "book-open",
+                "icon": "books",
                "groups": [
                    {
-                        "group": "General",
+                        "group": "Getting Started",
                        "pages": [
                            "docs/overview",
-                            "docs/getting-started",
+                            "docs/deployment-guide"
                            "docs/getting-started-selfhost"
                        ]
                    },
                    {
-                        "group": "Connecting your code",
+                        "group": "Features",
                        "pages": [
                            "docs/connections/overview",
                            {
-                                "group": "Supported platforms",
+                                "group": "Search",
                                "pages": [
                                    "docs/features/search/syntax-reference",
                                    "docs/features/search/multi-branch-indexing",
                                    "docs/features/search/search-contexts"
                                ]
                            },
                            "docs/features/code-navigation",
                            "docs/features/mcp-server",
                            {
                                "group": "Agents",
                                "tag": "experimental",
                                "pages": [
                                    "docs/features/agents/overview",
                                    "docs/features/agents/review-agent"
                                ]
                            }
                        ]
                    },
                    {
                        "group": "Configuration",
                        "pages": [
                            {
                                "group": "Connecting your code",
                                "pages": [
                                    "docs/connections/overview",
                                    "docs/connections/github",
                                    "docs/connections/gitlab",
                                    "docs/connections/bitbucket-cloud",
@ -42,65 +64,24 @@
                                    "docs/connections/local-repos",
                                    "docs/connections/request-new"
                                ]
-                            }
+                            },
-                        ]
+                            "docs/license-key",
-                    },
+                            "docs/configuration/environment-variables",
-                    {
+                            {
-                        "group": "Search",
+                                "group": "Authentication",
-                        "pages": [
+                                "pages": [
-                            "docs/search/syntax-reference",
+                                    "docs/configuration/auth/overview",
-                            "docs/search/multi-branch-indexing",
+                                    "docs/configuration/auth/roles-and-permissions"
-                            "docs/search/code-navigation",
+                                ]
-                            "docs/search/search-contexts"
+                            },
-                        ]
+                            "docs/configuration/transactional-emails"
                    },
                    {
                        "group": "Agents",
                        "pages": [
                            "docs/agents/overview",
                            "docs/agents/review-agent"
                        ]
                    },
                    {
                        "group": "More",
                        "pages": [
                            "docs/more/api-keys",
                            "docs/more/roles-and-permissions",
                            "docs/more/mcp-server"
                        ]
                    }
                ]
            },
            {
                "anchor": "Self Hosting",
                "icon": "server",
                "groups": [
                    {
                        "group": "Getting Started",
                        "pages": [
                            "self-hosting/overview",
                            "self-hosting/license-key"
                        ]
                    },
                    {
                        "group": "Configuration",
                        "pages": [
                            "self-hosting/configuration/environment-variables",
                            "self-hosting/configuration/authentication",
                            "self-hosting/configuration/transactional-emails",
                            "self-hosting/configuration/declarative-config"
                        ]
                    },
                    {
                        "group": "Security",
                        "pages": [
                        ]
                    },
                    {
                        "group": "Upgrade",
                        "pages": [
-                            "self-hosting/upgrade/v3-to-v4-guide",
+                            "docs/upgrade/v3-to-v4-guide",
-                            "self-hosting/upgrade/v2-to-v3-guide"
+                            "docs/upgrade/v2-to-v3-guide"
                        ]
                    }
                ]
@ -122,21 +103,18 @@
        "dark": "/logo/dark.png"
    },
    "navbar": {
        "links": [
            {
                "label": "GitHub",
                "href": "https://github.com/sourcebot-dev/sourcebot"
            }
        ],
        "primary": {
            "type": "button",
-            "label": "Sourcebot Cloud",
+            "label": "GitHub",
-            "href": "https://app.sourcebot.dev"
+            "href": "https://github.com/sourcebot-dev/sourcebot"
        }
    },
    "footer": {
        "socials": {
-            "github": "https://github.com/sourcebot-dev/sourcebot"
+            "github": "https://github.com/sourcebot-dev/sourcebot",
            "twitter": "https://x.com/sourcebot_dev",
            "discord": "https://discord.gg/Y6b78RqM",
            "linkedin": "https://www.linkedin.com/company/sourcebot"
        }
    },
    "integrations": {
@ -146,6 +124,6 @@
    },
    "appearance": {
        "default": "dark",
-        "strict": true
+        "strict": false
    }
 }
--- a/docs/self-hosting/configuration/authentication.mdx
+++ b/docs/self-hosting/configuration/authentication.mdx
@ -1,13 +1,10 @@
 ---
-title: Authentication
+title: Overview
 sidebarTitle: Authentication
 ---
 <Warning>Make sure the `AUTH_URL` environment variable is [configured correctly](/self-hosting/configuration) when using Sourcebot behind a domain.</Warning>
 Sourcebot has built-in authentication that gates access to your organization. OAuth, email codes, and email / password are supported. 
-The first account that's registered on a Sourcebot deployment is made the owner. All other users who register must be [approved](/self-hosting/configuration/authentication#approving-new-members) by the owner.
+The first account that's registered on a Sourcebot deployment is made the owner. All other users who register must be [approved](/docs/configuration/auth/overview#approving-new-members) by the owner.
 ![Login Page](/images/login.png)
@ -16,10 +13,10 @@ The first account that's registered on a Sourcebot deployment is made the owner.
 All account registrations after the first account must be approved by the owner. The owner can see all join requests by going into **Settings -> Members**.
-If you have an [enterprise license](/self-hosting/license-key), you can enable [AUTH_EE_ENABLE_JIT_PROVISIONING](/self-hosting/configuration/authentication#enterprise-authentication-providers) to 
+If you have an [enterprise license](/docs/license-key), you can enable [AUTH_EE_ENABLE_JIT_PROVISIONING](/docs/configuration/auth/overview#enterprise-authentication-providers) to 
 have Sourcebot accounts automatically created and approved on registration.
-You can setup emails to be sent when new join requests are created/approved by configurating [transactional emails](/self-hosting/configuration/transactional-emails)
+You can setup emails to be sent when new join requests are created/approved by configurating [transactional emails](/docs/configuration/transactional-emails)
 # Authentication Providers
 To enable an authentication provider in Sourcebot, configure the required environment variables for the provider. Under the hood, Sourcebot uses Auth.js which supports [many providers](https://authjs.dev/getting-started/authentication/oauth). Submit a [feature request on GitHub](https://github.com/sourcebot-dev/sourcebot/discussions/categories/ideas) if you want us to add support for a specific provider.
@ -39,11 +36,13 @@ Email codes are 6 digit codes sent to a provided email. Email codes are enabled
 - `EMAIL_FROM_ADDRESS`
-See [transactional emails](/self-hosting/configuration/transactional-emails) for more details.
+See [transactional emails](/docs/configuration/transactional-emails) for more details.
 ## Enterprise Authentication Providers
-The following authentication providers require an [enterprise license](/self-hosting/license-key) to be enabled.
+<Warning>If you're deploying Sourcebot behind a domain, you must set the [AUTH_URL](/docs/configuration/environment-variables) environment variable to use these providers.</Warning>
 The following authentication providers require an [enterprise license](/docs/license-key) to be enabled.
 By default, a new user registering using these providers must have their join request accepted by the owner of the organization to join. To allow a user to join automatically when
 they register for the first time, set the `AUTH_EE_ENABLE_JIT_PROVISIONING` environment variable to `true`. 
--- a/docs/docs/configuration/auth/roles-and-permissions.mdx
+++ b/docs/docs/configuration/auth/roles-and-permissions.mdx
--- a/docs/self-hosting/configuration/declarative-config.mdx
+++ b/docs/self-hosting/configuration/declarative-config.mdx
--- a/docs/self-hosting/configuration/environment-variables.mdx
+++ b/docs/self-hosting/configuration/environment-variables.mdx
@ -1,32 +1,33 @@
 ---
-title: Environment Variables 
+title: Environment variables 
-sidebarTitle: Environment Variables 
+sidebarTitle: Environment variables 
 mode: "wide"
 ---
-<Note>This page provides a detailed reference of all environment variables supported by Sourcebot. If you're just looking to get up and running, we recommend starting with the [getting started](/self-hosting/overview) guide instead.</Note>
+<Note>This page provides a detailed reference of all environment variables supported by Sourcebot. If you're just looking to get up and running, we recommend starting with the [deployment guide](/docs/deployment-guide) instead.</Note>
 ### Core Environment Variables
 The following environment variables allow you to configure your Sourcebot deployment.
 | Variable | Default | Description |
 | :------- | :------ | :---------- |
-| `AUTH_CREDENTIALS_LOGIN_ENABLED` | `true` | <p>Enables/disables authentication with basic credentials. Username and passwords are stored encrypted at rest within the postgres database. Checkout the [auth docs](/self-hosting/configuration/authentication) for more info</p> |
+| `AUTH_CREDENTIALS_LOGIN_ENABLED` | `true` | <p>Enables/disables authentication with basic credentials. Username and passwords are stored encrypted at rest within the postgres database. Checkout the [auth docs](/docs/configuration/auth/overview) for more info</p> |
-| `AUTH_EMAIL_CODE_LOGIN_ENABLED` | `false` | <p>Enables/disables authentication with a login code that's sent to a users email. `SMTP_CONNECTION_URL` and `EMAIL_FROM_ADDRESS` must also be set. Checkout the [auth docs](/self-hosting/configuration/authentication) for more info </p> |
+| `AUTH_EMAIL_CODE_LOGIN_ENABLED` | `false` | <p>Enables/disables authentication with a login code that's sent to a users email. `SMTP_CONNECTION_URL` and `EMAIL_FROM_ADDRESS` must also be set. Checkout the [auth docs](/docs/configuration/auth/overview) for more info </p> |
 | `AUTH_SECRET` | Automatically generated at startup if no value is provided. Generated using `openssl rand -base64 33` | <p>Used to validate login session cookies</p> |
 | `AUTH_URL` | - | <p>URL of your Sourcebot deployment, e.g., `https://example.com` or `http://localhost:3000`.</p> |
-| `CONFIG_PATH` | `-` | <p>The container relative path to the declerative configuration file. See [this doc](/self-hosting/configuration/declarative-config) for more info.</p> | 
+| `CONFIG_PATH` | `-` | <p>The container relative path to the declerative configuration file. See [this doc](/docs/configuration/declarative-config) for more info.</p> | 
 | `DATA_CACHE_DIR` | `$DATA_DIR/.sourcebot` | <p>The root data directory in which all data written to disk by Sourcebot will be located.</p> |
 | `DATA_DIR` | `/data` | <p>The directory within the container to store all persistent data. Typically, this directory will be volume mapped such that data is persisted across container restarts (e.g., `docker run -v $(pwd):/data`)</p> |
 | `DATABASE_DATA_DIR` | `$DATA_CACHE_DIR/db` | <p>The data directory for the default Postgres database.</p> |
 | `DATABASE_URL` | `postgresql://postgres@ localhost:5432/sourcebot` | <p>Connection string of your Postgres database. By default, a Postgres database is automatically provisioned at startup within the container.</p><p>If you'd like to use a non-default schema, you can provide it as a parameter in the database url </p> |
-| `EMAIL_FROM_ADDRESS` | `-` | <p>The email address that transactional emails will be sent from. See [this doc](/self-hosting/configuration/transactional-emails) for more info.</p> | 
+| `EMAIL_FROM_ADDRESS` | `-` | <p>The email address that transactional emails will be sent from. See [this doc](/docs/configuration/transactional-emails) for more info.</p> | 
 | `REDIS_DATA_DIR` | `$DATA_CACHE_DIR/redis` | <p>The data directory for the default Redis instance.</p> |
 | `REDIS_URL` | `redis://localhost:6379` | <p>Connection string of your Redis instance. By default, a Redis database is automatically provisioned at startup within the container.</p> |
 | `SHARD_MAX_MATCH_COUNT` | `10000` | <p>The maximum shard count per query</p> |
-| `SMTP_CONNECTION_URL` | `-` | <p>The url to the SMTP service used for sending transactional emails. See [this doc](/self-hosting/configuration/transactional-emails) for more info.</p> |
+| `SMTP_CONNECTION_URL` | `-` | <p>The url to the SMTP service used for sending transactional emails. See [this doc](/docs/configuration/transactional-emails) for more info.</p> |
 | `SOURCEBOT_ENCRYPTION_KEY` | Automatically generated at startup if no value is provided. Generated using `openssl rand -base64 24` | <p>Used to encrypt connection secrets and generate API keys.</p> |
 | `SOURCEBOT_LOG_LEVEL` | `info` | <p>The Sourcebot logging level. Valid values are `debug`, `info`, `warn`, `error`, in order of severity.</p> |
-| `SOURCEBOT_TELEMETRY_DISABLED` | `false` | <p>Enables/disables telemetry collection in Sourcebot. See [this doc](/self-hosting/security/telemetry) for more info.</p> |
+| `SOURCEBOT_TELEMETRY_DISABLED` | `false` | <p>Enables/disables telemetry collection in Sourcebot. See [this doc](/docs/overview.mdx#telemetry) for more info.</p> |
 | `TOTAL_MAX_MATCH_COUNT` | `100000` | <p>The maximum number of matches per query</p> |
 | `ZOEKT_MAX_WALL_TIME_MS` | `10000` | <p>The maximum real world duration (in milliseconds) per zoekt query</p> | 
--- a/docs/self-hosting/configuration/tenancy.mdx
+++ b/docs/self-hosting/configuration/tenancy.mdx
@ -4,7 +4,7 @@ sidebarTitle: Multi tenancy
 ---
 <Warning>If you're switching from single-tenant mode, delete the Sourcebot cache (the `.sourcebot` folder) before starting.</Warning>
-<Warning>[Authentication](/self-hosting/configuration/authentication) must be enabled to enable multi tenancy mode</Warning>
+<Warning>[Authentication](/docs/configuration/auth/overview) must be enabled to enable multi tenancy mode</Warning>
 Multi tenancy allows your Sourcebot deployment to have **multiple organizations**, each with their own set of members and repos. To enable multi tenancy mode, define an environment variable
 named `SOURCEBOT_TENANCY_MODE` and set its value to `multi`. When multi tenancy mode is enabled:
--- a/docs/self-hosting/configuration/transactional-emails.mdx
+++ b/docs/self-hosting/configuration/transactional-emails.mdx
@ -7,7 +7,7 @@ To enable transactional emails in your deployment, set the following environment
 - Send emails when new members are invited
 - Send emails when organization join requests are created/accepted
- Log into the Sourcebot deployment using [email codes](self-hosting/more/authentication#email-codes)
+- Log into the Sourcebot deployment using [email codes](/docs/configuration/auth/overview#email-codes)
 | Variable | Description |
 | :------- | :---------- |
--- a/docs/docs/connections/bitbucket-cloud.mdx
+++ b/docs/docs/connections/bitbucket-cloud.mdx
@ -1,12 +1,17 @@
 ---
 title: Linking code from Bitbucket Cloud
 sidebarTitle: Bitbucket Cloud
 icon: Bitbucket
 ---
 import BitbucketToken from '/snippets/bitbucket-token.mdx';
 import BitbucketAppPassword from '/snippets/bitbucket-app-password.mdx';
 import BitbucketSchema from '/snippets/schemas/v3/bitbucket.schema.mdx'
 <Note>
 Looking for docs on Bitbucket Data Center? See [this doc](/docs/connections/bitbucket-data-center).
 </Note>
 ## Examples
 <AccordionGroup>
--- a/docs/docs/connections/bitbucket-data-center.mdx
+++ b/docs/docs/connections/bitbucket-data-center.mdx
@ -1,12 +1,17 @@
 ---
 title: Linking code from Bitbucket Data Center
 sidebarTitle: Bitbucket Data Center
 icon: Bitbucket
 ---
 import BitbucketToken from '/snippets/bitbucket-token.mdx';
 import BitbucketAppPassword from '/snippets/bitbucket-app-password.mdx';
 import BitbucketSchema from '/snippets/schemas/v3/bitbucket.schema.mdx'
 <Note>
 Looking for docs on Bitbucket Cloud? See [this doc](/docs/connections/bitbucket-cloud).
 </Note>
 ## Examples
 <AccordionGroup>
--- a/docs/docs/connections/generic-git-host.mdx
+++ b/docs/docs/connections/generic-git-host.mdx
@ -1,5 +1,6 @@
 ---
 title: Other Git hosts
 icon: git-alt
 ---
 import GenericGitHost from '/snippets/schemas/v3/genericGitHost.schema.mdx'
--- a/docs/docs/connections/gerrit.mdx
+++ b/docs/docs/connections/gerrit.mdx
@ -1,6 +1,7 @@
 ---
 title: Linking code from Gerrit
 sidebarTitle: Gerrit
 icon: crow
 ---
 import GerritSchema from '/snippets/schemas/v3/gerrit.schema.mdx'
--- a/docs/docs/connections/gitea.mdx
+++ b/docs/docs/connections/gitea.mdx
@ -1,6 +1,7 @@
 ---
 title: Linking code from Gitea
 sidebarTitle: Gitea
 icon: mug-tea
 ---
 import GiteaSchema from '/snippets/schemas/v3/gitea.schema.mdx'
@ -82,7 +83,7 @@ Next, provide the access token via the `token` property, either as an environmen
 <Tabs>
    <Tab title="Environment Variable">
-        <Note>Environment variables are only supported in a [declarative config](/self-hosting/configuration/declarative-config) and cannot be used in the web UI.</Note>
+        <Note>Environment variables are only supported in a [declarative config](/docs/configuration/declarative-config) and cannot be used in the web UI.</Note>
        1. Add the `token` property to your connection config:
        ```json
@ -107,7 +108,7 @@ Next, provide the access token via the `token` property, either as an environmen
    </Tab>
    <Tab title="Secret">
-        <Note>Secrets are only supported when [authentication](/self-hosting/configuration/authentication) is enabled.</Note>
+        <Note>Secrets are only supported when [authentication](/docs/configuration/auth/overview) is enabled.</Note>
        1. Navigate to **Secrets** in settings and create a new secret with your PAT:
--- a/docs/docs/connections/github.mdx
+++ b/docs/docs/connections/github.mdx
@ -1,6 +1,7 @@
 ---
 title: Linking code from GitHub
 sidebarTitle: GitHub
 icon: GitHub
 ---
 import GitHubSchema from '/snippets/schemas/v3/github.schema.mdx'
@ -111,7 +112,7 @@ Next, provide the PAT via the `token` property, either as an environment variabl
 <Tabs>
    <Tab title="Environment Variable">
-        <Note>Environment variables are only supported in a [declarative config](/self-hosting/configuration/declarative-config) and cannot be used in the web UI.</Note>
+        <Note>Environment variables are only supported in a [declarative config](/docs/configuration/declarative-config) and cannot be used in the web UI.</Note>
        1. Add the `token` property to your connection config:
        ```json
@ -136,7 +137,7 @@ Next, provide the PAT via the `token` property, either as an environment variabl
    </Tab>
    <Tab title="Secret">
-        <Note>Secrets are only supported when [authentication](/self-hosting/configuration/authentication) is enabled.</Note>
+        <Note>Secrets are only supported when [authentication](/docs/configuration/auth/overview) is enabled.</Note>
        1. Navigate to **Secrets** in settings and create a new secret with your PAT:
--- a/docs/docs/connections/gitlab.mdx
+++ b/docs/docs/connections/gitlab.mdx
@ -1,6 +1,7 @@
 ---
 title: Linking code from GitLab
 sidebarTitle: GitLab
 icon: GitLab
 ---
 import GitLabSchema from '/snippets/schemas/v3/gitlab.schema.mdx'
@ -116,7 +117,7 @@ Next, provide the PAT via the `token` property, either as an environment variabl
 <Tabs>
    <Tab title="Environment Variable">
-        <Note>Environment variables are only supported in a [declarative config](/self-hosting/configuration/declarative-config) and cannot be used in the web UI.</Note>
+        <Note>Environment variables are only supported in a [declarative config](/docs/configuration/declarative-config) and cannot be used in the web UI.</Note>
        1. Add the `token` property to your connection config:
        ```json
@ -141,7 +142,7 @@ Next, provide the PAT via the `token` property, either as an environment variabl
    </Tab>
    <Tab title="Secret">
-        <Note>Secrets are only supported when [authentication](/self-hosting/configuration/authentication) is enabled.</Note>
+        <Note>Secrets are only supported when [authentication](/docs/configuration/auth/overview) is enabled.</Note>
        1. Navigate to **Secrets** in settings and create a new secret with your PAT:
--- a/docs/docs/connections/local-repos.mdx
+++ b/docs/docs/connections/local-repos.mdx
@ -1,13 +1,10 @@
 ---
 title: Local Git repositories
 icon: folder
 ---
 import GenericGitHost from '/snippets/schemas/v3/genericGitHost.schema.mdx'
 <Note>
 This feature is only supported when [self-hosting](/self-hosting/overview).
 </Note>
 Sourcebot can sync code from generic git repositories stored in a local directory. This can be helpful in scenarios where you already have a large number of repos already checked out. Local repositories are treated as **read-only**, meaing Sourcebot will **not** `git fetch` new revisions.
 ## Getting Started
--- a/docs/docs/connections/overview.mdx
+++ b/docs/docs/connections/overview.mdx
@ -4,27 +4,88 @@ sidebarTitle: Overview
 ---
 import SupportedPlatforms from '/snippets/platform-support.mdx'
 import ConfigSchema from '/snippets/schemas/v3/index.schema.mdx'
-To connect your code to Sourcebot you create **connections**. A **connection** is a configuration object that describes how Sourcebot should fetch information from a supported code host.
+A **connection** in Sourcebot represents a link to a code host (such as GitHub, GitLab, Bitbucket, etc.). Each connection defines how Sourcebot should authenticate and interact with a particular host, and which repositories to sync and index from that host. Connections are uniquely identified by their name.
-There are two ways to define connections:
+A JSON configuration file is used to specify connections. For example:
-<AccordionGroup>
+```json
-    <Accordion title="Declarative configuration file">
+// Specifies two connections:
-        This is only supported when self-hosting, and is the default mechanism to define connections. Connections are defined in a [JSON file](/self-hosting/configuration/declarative-config)
+{
-        and the path to the file is provided through the `CONFIG_PATH` environment variable
+    "$schema": "https://raw.githubusercontent.com/sourcebot-dev/sourcebot/main/schemas/v3/index.json",
-    </Accordion>
+    "connections": {
-    <Accordion title="UI connection management">
+        // 1. A connection to GitHub.com
-        This is the only way to define connections when using Sourcebot Cloud, and can be configured when self-hosting by enabling [authentication](/self-hosting/configuration/authentications).
+        "github-connection": {
            "type": "github",
            "repos": [
                "sourcebot-dev/sourcebot"
            ],
            "token": {
                "env": "GITHUB_TOKEN"
            }
        },
        // 2. A self-hosted GitLab instance
        "gitlab-connection": {
            "type": "gitlab",
            "url": "https://gitlab.example.com",
            "groups": [
                "my-group",
                "my-other-group/sub-group"
            ],
            "token": {
                "env": "GITLAB_TOKEN"
            }
        }
    }
 }
 ```
-        In this method, connections are defined and managed within the webapp:
+Configuration files must conform to the [JSON schema](#schema-reference).
-        ![Connections page](/images/connection_page.png)
+When running Sourcebot, this file must be mounted in a volume that is accessible to the container, with it's path specified in the `CONFIG_PATH` environment variable. For example:
    </Accordion>
 </AccordionGroup>
-### Supported code hosts
+```bash
 docker run \
    -v $(pwd)/config.json:/data/config.json \
    -e CONFIG_PATH=/data/config.json \
    ... \ # other config
    ghcr.io/sourcebot-dev/sourcebot:latest
 ```
 Sourcebot performs syncing in the background. Syncing consists of two steps:
 1. Fetch the latest changes from `HEAD` (and any [additional branches](/docs/features/search/multi-branch-indexing)) from the code host.
 2. Re-indexes the repository.
 This is processed in a [job queue](/docs/overview#architecture), and is parallelized across multiple worker processes. Jobs will take longer to complete the first time a repository is synced, or when a diff is large.
 On the home page, you can view the sync status of ongoing jobs:
 <video
    autoPlay
    muted
    loop
    playsInline
    className="w-full aspect-video"
    src="https://framerusercontent.com/assets/7YyxK8ctPEy9Rf68X2kIdMI.mp4"
 ></video>
 ## Getting started
 ---
 To get started, pick a platform below and follow the instructions to connect your code.
 <SupportedPlatforms />
 <Note>Missing your code host? [Submit a feature request on GitHub](https://github.com/sourcebot-dev/sourcebot/discussions/categories/ideas).</Note>
 ## Schema reference
 ---
 <Accordion title="Reference">
 [schemas/v3/index.json](https://github.com/sourcebot-dev/sourcebot/blob/main/schemas/v3/index.json)
 <ConfigSchema />
 </Accordion>
--- a/docs/docs/connections/request-new.mdx
+++ b/docs/docs/connections/request-new.mdx
@ -2,6 +2,7 @@
 sidebarTitle: Request another host
 url: https://github.com/sourcebot-dev/sourcebot/discussions/categories/ideas
 title: Request another code host
 icon: plus
 ---
 Is your code host not supported? Please open a [feature request](https://github.com/sourcebot-dev/sourcebot/discussions/categories/ideas).
--- a/docs/docs/deployment-guide.mdx
+++ b/docs/docs/deployment-guide.mdx
@ -0,0 +1,105 @@
 ---
 title: "Deployment guide"
 ---
 import SupportedPlatforms from '/snippets/platform-support.mdx'
 The following guide will walk you through the steps to deploy Sourcebot on your own infrastructure. Sourcebot is distributed as a [single docker container](/docs/overview#architecture) that can be deployed to a k8s cluster, a VM, or any platform that supports docker.
 ## Walkthrough video
 ---
 Watch this 1:51 minute video to get a quick overview of how to deploy Sourcebot using Docker.
 <iframe
    src="https://www.youtube.com/embed/1_JCr05haWc"
    title="YouTube video player"
    frameborder="0"
    allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
    allowfullscreen
    className="aspect-video w-full"
 ></iframe>
 ## Step-by-step guide
 ---
 <Note>Hit an issue? Please let us know on [GitHub discussions](https://github.com/sourcebot-dev/sourcebot/discussions/categories/support) or by [emailing us](mailto:team@sourcebot.dev).</Note>
 <Steps>
    <Step title="Requirements">
        - Docker -> use [Docker Desktop](https://www.docker.com/products/docker-desktop/) on Mac or Windows.
    </Step>
    <Step title="Create a config.json">
        Create a `config.json` file that tells Sourcebot which repositories to sync and index:
        ```bash
        touch config.json
        echo '{
            "$schema": "https://raw.githubusercontent.com/sourcebot-dev/sourcebot/main/schemas/v3/index.json",
            "connections": {
                // 
                "starter-connection": {
                    "type": "github",
                    "repos": [
                        "sourcebot-dev/sourcebot"
                    ]
                }
            }
        }' > config.json
        ```
        This config creates a single GitHub connection named `starter-connection` that specifies [Sourcebot](https://github.com/sourcebot-dev/sourcebot) as a repo to sync. [Learn more about the config file](/docs/connections/overview).
    </Step>
    <Step title="Launch your instance">
        In the same directory as `config.json`, run the following command to start your instance:
        ``` bash
        docker run \
            -p 3000:3000 \
            --pull=always \
            --rm \
            -v $(pwd):/data \
            -e CONFIG_PATH=/data/config.json \
            --name sourcebot \
            ghcr.io/sourcebot-dev/sourcebot:latest
        ```
        Navigate to `localhost:3000` to start searching the Sourcebot repo.
        <Accordion title="Details">
            **This command**:
                - pulls the latest version of the `sourcebot` docker image.
                - mounts the working directory to `/data` in the container to allow Sourcebot to persist data across restarts, and to access the `config.json`. In your local directory, you should see a `.sourcebot` folder created that contains all persistent data.
                - runs any pending database migrations.
                - starts up all services, including the webserver exposed on port 3000.
                - reads `config.json` and starts syncing.
        </Accordion>
    </Step>
    <Step title="Login">
        Navigate to `http://localhost:3000` and create an account. The first account which is registered on a fresh Sourcebot deployment is given the [owner role](/docs/configuration/auth/roles-and-permissions).
        <Note>
            By default, only email / password authentication is enabled. [Learn more about authentication](/docs/configuration/auth/overview).
        </Note>
    </Step>
    <Step title="Done">
        You're all set! You can now start searching - checkout the [syntax guide](/docs/features/search/syntax-reference) to learn more about how to search.
    </Step>
 </Steps>
 ## Next steps
 ---
 <CardGroup cols={2}>
    <Card title="Connecting your code" icon="code" href="/docs/connections/overview">
        Learn more about how to connect your code to Sourcebot.
    </Card>
    <Card title="Setup other authentication providers" icon="lock" href="/docs/configuration/auth/overview">
        Learn more about how to setup SSO, email codes, and other authentication providers.
    </Card>
 </CardGroup>
--- a/docs/docs/features/agents/overview.mdx
+++ b/docs/docs/features/agents/overview.mdx
@ -3,15 +3,15 @@ title: "Agents Overview"
 sidebarTitle: "Overview"
 ---
-<Note>
+<Warning>
-Have an idea for an agent that we haven't built? Submit a [feature request](https://github.com/sourcebot-dev/sourcebot/discussions/categories/feature-requests) on our GitHub
+Agents are currently a experimental feature. Have an idea for an agent that we haven't built? Submit a [feature request](https://github.com/sourcebot-dev/sourcebot/discussions/categories/feature-requests) on our GitHub.
-</Note>
+</Warning>
 Agents are automations that leverage the code indexed on Sourcebot to perform a specific task. Once you've setup Sourcebot, check out the
 guides below to configure additional agents.
 <CardGroup cols={2}>
-    <Card horizontal title="Review Agent" icon="gear" href="/docs/agents/review-agent">
+    <Card horizontal title="Review Agent" icon="gear" href="/docs/features/agents/review-agent">
        An AI agent that reviews your PRs to identify issues
    </Card>
 </CardGroup>
--- a/docs/docs/features/agents/review-agent.mdx
+++ b/docs/docs/features/agents/review-agent.mdx
@ -10,7 +10,7 @@ codebase that the agent may fetch to perform the review.
 This agent provides codebase-aware reviews for your PRs. For each diff, this agent fetches relevant context from Sourcebot and feeds it into an LLM for a detailed review of your changes.
-The AI Code Review Agent is [open source](https://github.com/sourcebot-dev/sourcebot/tree/main/packages/web/src/features/agents/review-agent) and packaged in [Sourcebot](https://github.com/sourcebot-dev/sourcebot). To get started using this agent, [deploy Sourcebot](/self-hosting/overview)
+The AI Code Review Agent is [open source](https://github.com/sourcebot-dev/sourcebot/tree/main/packages/web/src/features/agents/review-agent) and packaged in [Sourcebot](https://github.com/sourcebot-dev/sourcebot). To get started using this agent, [deploy Sourcebot](/docs/deployment-guide)
 and then follow the configuration instructions below.
 ![AI Code Review Agent Example](/images/review_agent_example.png)
--- a/docs/docs/features/code-navigation.mdx
+++ b/docs/docs/features/code-navigation.mdx
@ -4,10 +4,9 @@ sidebarTitle: Code navigation
 ---
 import SearchContextSchema from '/snippets/schemas/v3/searchContext.schema.mdx'
 import LicenseKeyRequired from '/snippets/license-key-required.mdx'
-<Note>
+<LicenseKeyRequired />
 This feature is only available in [Sourcebot cloud](app.sourcebot.dev) or with an active Enterprise license when [self-hosting](/self-hosting). Please add your [license key](/self-hosting/license-key) to activate it.
 </Note>
 **Code navigation** allows you to jump between symbol definition and references when viewing source files in Sourcebot. This feature is enabled **automatically** when a valid license key is present and works with all popular programming languages.
@ -25,7 +24,7 @@ This feature is only available in [Sourcebot cloud](app.sourcebot.dev) or with a
 ## How does it work?
-Code navigation is **search-based**, meaning it uses the same code search engine and [query language](/docs/search/syntax-reference) to estimate a symbol's references and definitions. We refer to these estimations as "search heuristics". We have two search heuristics to enable the following operations:
+Code navigation is **search-based**, meaning it uses the same code search engine and [query language](/docs/features/search/syntax-reference) to estimate a symbol's references and definitions. We refer to these estimations as "search heuristics". We have two search heuristics to enable the following operations:
 ### Find references
 Given a `symbolName`, along with information about the file the symbol is contained within (`git_revision`, and `language`), runs the following search:
--- a/docs/docs/features/mcp-server.mdx
+++ b/docs/docs/features/mcp-server.mdx
@ -3,21 +3,25 @@ title: Sourcebot MCP server (@sourcebot/mcp)
 sidebarTitle: Sourcebot MCP server
 ---
 <Note>
 This feature is only available when [self-hosting](/self-hosting)
 </Note>
 The [Model Context Protocol](https://modelcontextprotocol.io/introduction) (MCP) is an open standard for providing context to LLMs. The [@sourcebot/mcp](https://www.npmjs.com/package/@sourcebot/mcp) package is a MCP server that enables LLMs to interface with your Sourcebot instance, enabling MCP clients like Cursor, Vscode, and others to have context over your entire codebase.
 ## Getting Started
 <Steps>
    <Step title="Launch Sourcebot">
-        Follow the self-hosting [quick start guide](/self-hosting/overview#quick-start-guide) to launch Sourcebot and get your code indexed. The host url of your instance (e.g., `http://localhost:3000`) is passed to the MCP server via the `SOURCEBOT_HOST` url.
+        Follow the [deployment guide](/docs/deployment-guide) to launch Sourcebot and get your code indexed. The host url of your instance (e.g., `http://localhost:3000`) is passed to the MCP server via the `SOURCEBOT_HOST` url.
        If a host is not provided, then the server will fallback to using the demo instance hosted at https://demo.sourcebot.dev. You can see the list of repositories indexed [here](https://demo.sourcebot.dev/~/repos). Add additional repositories by [opening a PR](https://github.com/sourcebot-dev/sourcebot/blob/main/demo-site-config.json).
    </Step>
    <Step title="Create an API key">
        Create an API key to allow the MCP server to query your Sourcebot instance. To create an API key, login to your Sourcebot instance and navigate to **Settings -> API Keys**:
        ![API Keys UI](/images/api_key.png)
        Copy the API key and set it as the `SOURCEBOT_API_KEY` environment variable.
    </Step>
    <Step title="Install the MCP server">
        <Note>
            Ensure you have [Node.js](https://nodejs.org/en) >= v18.0.0 installed.
@ -39,7 +43,8 @@ The [Model Context Protocol](https://modelcontextprotocol.io/introduction) (MCP)
                            "command": "npx",
                            "args": ["-y", "@sourcebot/mcp@latest" ],
                            "env": {
-                                "SOURCEBOT_HOST": "http://localhost:3000"
+                                "SOURCEBOT_HOST": "http://localhost:3000",
                                "SOURCEBOT_API_KEY": "your-api-key"
                            }
                        }
                    }
@ -62,7 +67,8 @@ The [Model Context Protocol](https://modelcontextprotocol.io/introduction) (MCP)
                            "command": "npx",
                            "args": ["-y", "@sourcebot/mcp@latest" ],
                            "env": {
-                                "SOURCEBOT_HOST": "http://localhost:3000"
+                                "SOURCEBOT_HOST": "http://localhost:3000",
                                "SOURCEBOT_API_KEY": "your-api-key"
                            }
                        }
                    }
@ -86,7 +92,8 @@ The [Model Context Protocol](https://modelcontextprotocol.io/introduction) (MCP)
                                "command": "npx",
                                "args": ["-y", "@sourcebot/mcp@latest"],
                                "env": {
-                                    "SOURCEBOT_HOST": "http://localhost:3000"
+                                    "SOURCEBOT_HOST": "http://localhost:3000",
                                    "SOURCEBOT_API_KEY": "your-api-key"
                                }
                            }
                        }
@ -102,7 +109,7 @@ The [Model Context Protocol](https://modelcontextprotocol.io/introduction) (MCP)
                Run the following command:
                ```sh
-                claude mcp add sourcebot -e SOURCEBOT_HOST=http://localhost:3000 -- npx -y @sourcebot/mcp@latest
+                claude mcp add sourcebot -e SOURCEBOT_HOST=http://localhost:3000 -e SOURCEBOT_API_KEY=your-api-key -- npx -y @sourcebot/mcp@latest
                ```
                Replace `http://localhost:3000` with wherever your Sourcebot instance is hosted.
@ -119,7 +126,8 @@ The [Model Context Protocol](https://modelcontextprotocol.io/introduction) (MCP)
                            "command": "npx",
                            "args": ["-y", "@sourcebot/mcp@latest"],
                            "env": {
-                                "SOURCEBOT_HOST": "http://localhost:3000"
+                                "SOURCEBOT_HOST": "http://localhost:3000",
                                "SOURCEBOT_API_KEY": "your-api-key"
                            }
                        }
                    }
--- a/docs/docs/features/search/multi-branch-indexing.mdx
+++ b/docs/docs/features/search/multi-branch-indexing.mdx
--- a/docs/docs/features/search/search-contexts.mdx
+++ b/docs/docs/features/search/search-contexts.mdx
@ -4,10 +4,9 @@ sidebarTitle: Search contexts
 ---
 import SearchContextSchema from '/snippets/schemas/v3/searchContext.schema.mdx'
 import LicenseKeyRequired from '/snippets/license-key-required.mdx'
-<Note>
+<LicenseKeyRequired />
 This feature is only available when [self-hosting](/self-hosting) with an active Enterprise license. Please add your [license key](/self-hosting/license-key) to activate it.
 </Note>
 A **search context** is a user-defined grouping of repositories that helps focus searches on specific areas of your codebase, like frontend, backend, or infrastructure code. Some example queries using search contexts:
@ -16,7 +15,7 @@ A **search context** is a user-defined grouping of repositories that helps focus
 - `( context:project1 or context:project2 ) logger\.debug` - search for debug log calls in project1 and project2 
-Search contexts are defined in the `context` object inside of a [declarative config](/self-hosting/configuration/declarative-config). Repositories can be included / excluded from a search context by specifying the repo's URL in either the `include` array or `exclude` array. Glob patterns are supported.
+Search contexts are defined in the `context` object inside of a [declarative config](/docs/configuration/declarative-config). Repositories can be included / excluded from a search context by specifying the repo's URL in either the `include` array or `exclude` array. Glob patterns are supported.
 ## Example
@ -41,7 +40,7 @@ shared/
 ├─ ...
 ```
-To make searching easier, we can create three search contexts in our [config.json](/self-hosting/configuration/declarative-config):
+To make searching easier, we can create three search contexts in our [config.json](/docs/configuration/declarative-config):
 - `web`: For all frontend-related code
 - `backend`: For backend services and shared APIs
 - `pipelines`: For all CI/CD configurations
@ -105,7 +104,7 @@ Like other prefixes, contexts can be negated using `-` or combined using `or`:
 - `-context:web` excludes frontend repositories from results
 - `( context:web or context:backend )` searches across both frontend and backend code
-See [this doc](/docs/search/syntax-reference) for more details on the search query syntax.
+See [this doc](/docs/features/search/syntax-reference) for more details on the search query syntax.
 ## Schema reference
--- a/docs/docs/features/search/syntax-reference.mdx
+++ b/docs/docs/features/search/syntax-reference.mdx
@ -32,4 +32,4 @@ Expressions can be prefixed with certain keywords to modify search behavior. Som
 | `rev:` | Filter results from a specific branch or tag. By default **only** the default branch is searched. | `rev:beta` - Filter results to branches that match regex `/beta/` |
 | `lang:` | Filter results by language (as defined by [linguist](https://github.com/github-linguist/linguist/blob/main/lib/linguist/languages.yml)). By default all languages are searched. | `lang:TypeScript` - Filter results to TypeScript files<br/>`-lang:YAML` - Ignore results from YAML files |
 | `sym:` | Match symbol definitions created by [universal ctags](https://ctags.io/) at index time. | `sym:\bmain\b` - Filter results to symbols that match regex `/\bmain\b/` |
-| `context:` | Filter results to a predefined [search context](/docs/search/search-contexts). | `context:web` - Filter results to the web context<br/>`-context:pipelines` - Ignore results from the pipelines context |
+| `context:` | Filter results to a predefined [search context](/docs/features/search/search-contexts). | `context:web` - Filter results to the web context<br/>`-context:pipelines` - Ignore results from the pipelines context |
--- a/docs/docs/getting-started-selfhost.mdx
+++ b/docs/docs/getting-started-selfhost.mdx
@ -1,8 +0,0 @@
 ---
 sidebarTitle: Quick start guide (self-host)
 url: /self-hosting/overview
 ---
 {/*This page acts as a navigation link*/}
 [Quick start guide (self-host)](/self-hosting/overview)
--- a/docs/docs/getting-started.mdx
+++ b/docs/docs/getting-started.mdx
@ -1,55 +0,0 @@
 ---
 title: Cloud quick start guide
 sidebarTitle: Quick start guide (cloud)
 ---
 <Note>Looking for a self-hosted solution? Checkout our [self-hosting docs](/self-hosting/overview).</Note>
 This page will provide a quick walkthrough of how to get onboarded on Sourcebot, import your code, and start searching.
 {/*@todo: record a quick start guide
 <iframe
    width="560"
    height="315"
    src="https://www.youtube.com/embed/4KzFe50RQkQ"
    title="YouTube video player"
    frameborder="0"
    allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
    allowfullscreen
 ></iframe>
 */}
 <Steps>
    <Step title="Register an account">
        Head over to [app.sourcebot.dev](https://app.sourcebot.dev) and create an account.
    </Step>
    <Step title="Create an organization">
        After logging in, you'll be asked to create an organization. You'll invite your team members to this organization later so they can also use Sourcebot.
        ![Org Creation](/images/org_create.png)
    </Step>
    <Step title="Link your code host">
        After selecting a code host you want to connect to, you'll be presented with the connection creation page. This page has the following three inputs:
        - Connection name (required): The name of the connection within Sourcebot
        - Secret (optional): An [access token](/access-tokens/overview) that is used to fetch private repos
        - Configuration: The JSON configuration schema that defines the repos/orgs to fetch. 
        For a more detailed explanation of connections, check out the [Connections](/docs/connections/overview) page.
        The example below shows a connection named `sourcebot-org` that fetches all of the repos for the `sourcebot-dev` GitHub organization, but excludes the `sourcebot-dev/zoekt` repo
        <Note>This page won't let you continue with an invalid connection schema. If you're hitting errors, make sure the input you're providing is a valid JSON</Note> 
        ![Connection Create Example](/images/create_connection_example.png)
    </Step>
 </Steps>
 ### Search
 Once you create your organization's first connection successfully, you'll be redirected to your org's main search page. From here, you can use the search bar to search across all
 of the repos you've indexed
 ![Onboard Complete](/images/onboard_complete.png)
 Congrats, you've successfuly setup Sourcebot! Read on to learn more about the Sourcebot's capabilities. Checkout the [Connections](/docs/connections/overview) page to learn how to control which repos Sourcebot fetches
--- a/docs/docs/license-key.mdx
+++ b/docs/docs/license-key.mdx
@ -0,0 +1,43 @@
 ---
 title: License key
 sidebarTitle: License key
 ---
 <Note>
 If you'd like a trial license, [reach out](https://www.sourcebot.dev/contact) and we'll send one over within 24 hours
 </Note>
 All core Sourcebot features are available in Sourcebot OSS (MIT Licensed) without any limits. Some additional features require a license key. See the [pricing page](https://www.sourcebot.dev/pricing) for more details.
 ## Activating a license key
 ---
 After purchasing a license key, you can activate it by setting the `SOURCEBOT_EE_LICENSE_KEY` environment variable.
 ```bash
 docker run \
    -e SOURCEBOT_EE_LICENSE_KEY=<your-license-key> \
    /* additional args */ \
    ghcr.io/sourcebot-dev/sourcebot:latest
 ```
 ## Feature availability
 ---
 | Feature | OSS | Licensed |
 |:---------|:-----|:----------|
 | [Search](/docs/features/search/syntax-reference) | ✅ | ✅ |
 | [Full code host support](/docs/connections/overview) | ✅ | ✅ |
 | [MCP Server](/docs/features/mcp-server) | ✅ | ✅ | 
 | [Agents](/docs/features/agents/overview) | ✅ | ✅ |
 | [Login with credentials](/docs/configuration/auth/overview) | ✅ | ✅ |
 | [Login with email codes](/docs/configuration/auth/overview) | ✅ | ✅ |
 | [Login with SSO](/docs/configuration/auth/overview#enterprise-authentication-providers) | 🛑 | ✅ |
 | [Code navigation](/docs/features/code-navigation) | 🛑 | ✅ |
 | [Search contexts](/docs/features/search/search-contexts) | 🛑 | ✅ |
 ## Questions?
 If you have any questions regarding licensing, please [contact us](https://www.sourcebot.dev/contact).
--- a/docs/docs/more/api-keys.mdx
+++ b/docs/docs/more/api-keys.mdx
@ -1,8 +0,0 @@
 ---
 title: API Keys
 ---
 An API Key is required when querying Sourcebot outside the context of the web app client (ex. MCP server, review agent). To create an API key, login to your Sourcebot instance and navigate to
 **Settings -> API Keys**:
 ![API Keys UI](/images/api_key.png)
--- a/docs/docs/overview.mdx
+++ b/docs/docs/overview.mdx
@ -2,19 +2,194 @@
 title: "Overview"
 ---
-Sourcebot is an **[open-source](https://github.com/sourcebot-dev/sourcebot) code search tool** that is purpose built to search multi-million line codebases in seconds. It integrates with [GitHub](/docs/connections/github), [GitLab](/docs/connections/gitlab), and [other platforms](/docs/connections).
+> Sourcebot is an open-source ([GitHub](https://github.com/sourcebot-dev/sourcebot)), self-hosted code search tool that is purpose built to help teams find and navigate code quickly, at scale.
-## Getting Started
+<AccordionGroup>
  <Accordion title="Why Sourcebot?">
    - **Full-featured search:** Fast indexed-based search with regex support, filters, branch search, boolean logic, and more.
    - **Self-hosted:** Ships as a single [docker container](https://github.com/sourcebot-dev/sourcebot/pkgs/container/sourcebot) that can be deployed anywhere.
    - **Modern design:** Light/Dark mode, vim keybindings, keyboard shortcuts, syntax highlighting, etc.
    - **Scalable:** Scales to millions of lines of code.
    - **Open-source:** Core features are MIT licensed, no vendor lock-in.
  </Accordion>
 </AccordionGroup>
-There are two ways to get started using Sourcebot:
+## Features
 ---
 <Info>
  Find an overview of all Sourcebot features below. For details, see the individual documentation pages.
 </Info>
 ### Fast-indexed based search
 Search across millions of lines of code in seconds using Sourcebot's blazingly fast indexed search. Find exactly what you are looking for with regular expressions, search filters, boolean logic, and more.
 <Accordion title="Key benefits">
 - **Regex support:** Use regular expressions to find code with precision.
 - **Query language:** Scope searches to specific files, repos, languages, symbol definitions and more using a rich [query language](/docs/features/search/syntax-reference).
 - **Branch search:** Specify a list of branches to search across ([docs](/docs/features/search/multi-branch-indexing)).
 - **Fast & scalable:** Sourcebot uses [trigram indexing](https://en.wikipedia.org/wiki/Trigram_search), allowing it to scale to massive codebases.
 - **Syntax highlighting:** Syntax highlighting support for over [100+ languages](https://github.com/sourcebot-dev/sourcebot/blob/57724689303f351c279d37f45b6406f1d5d5d5ab/packages/web/src/lib/codemirrorLanguage.ts#L125).
 - **Multi-repository:** Search across all of your repositories in a single search.
 - **Search suggestions:** Get search suggestions as you craft your query.
 - **Filter panel:** Filter results by repository or by language.
 </Accordion>
 <video
  autoPlay
  muted
  loop
  playsInline
  className="w-full aspect-video"
  src="https://framerusercontent.com/assets/cEqHNSLiMbNeG3bk5xheQWXmKqc.mp4"
 ></video>
 ### Code Navigation
 [Code navigation](/docs/features/code-navigation) helps you jump between symbol definitions and references quickly when browsing source code in Sourcebot.
 <Accordion title="Key benefits">
 - **Hover popover:** Hovering over a symbol reveals the symbol's definition signature in a inline preview.
 - **Go to definition:** Navigate to a symbol's definition(s).
 - **Find references:** Get all references to a symbol.
 - **Cross-repository:** Sourcebot can resolve references and definitions across repositories.
 </Accordion>
 <video
  autoPlay
  muted
  loop
  playsInline
  className="w-full aspect-video"
  src="https://framerusercontent.com/assets/B9ZxrlsUeO9NJyzkKyvVV2KSU4.mp4"
 ></video>
 ### Cross code-host support
 Connect your code from multiple code-host platforms and search across all of them from a single interface.
 <Accordion title="Key benefits">
 - **Auto re-syncing:** Sourcebot will periodically sync with code hosts to pull the latest changes.
 - **Flexible configuration:** Sourcebot uses an expressive [JSON schema](/docs/connections/overview) config format to specify exactly what repositories to index (and what not to index).
 - **Parallel indexing:** Repositories are indexed in parallel.
 </Accordion>
 <Columns cols={4}>
  <Tooltip tip="GitHub.com | Enterprise Server | Enterprise Cloud">
    <Card title="GitHub" img="/images/github.png" href="/docs/connections/github" />
  </Tooltip>
  <Tooltip tip="GitLab.com | Self Managed (CE & EE) | Dedicated">
    <Card title="GitLab" img="/images/gitlab.png" href="/docs/connections/gitlab" />
  </Tooltip>
  <Tooltip tip="Bitbucket cloud | Bitbucket Data Center">
    <Card title="BitBucket" img="/images/bitbucket.png" href="/docs/connections/bitbucket-cloud" />
  </Tooltip>
  <Tooltip tip="Gitea.com | Gitea Self-hosted">
    <Card title="Gitea" img="/images/gitea.png" href="/docs/connections/gitea" />
  </Tooltip>
  <Card title="Gerrit" img="/images/gerrit.png" href="/docs/connections/gerrit" />
  <Card title="Other Git Hosts" img="/images/git.png" href="/docs/connections/generic-git-host" />
  <Card title="Local Git Repos" img="/images/local.png" href="/docs/connections/local-repos" />
 </Columns>
 ### Authentication
 Sourcebot comes with built-in support for authentication via [email/password](/docs/configuration/auth/overview#email-%2F-password), [email codes](/docs/configuration/auth/overview#email-codes), and various [SSO providers](/docs/configuration/auth/overview#enterprise-authentication-providers).
 <Accordion title="Key benefits">
 - **Configurable auth providers:** Configure the auth providers that are available to your team.
 - **SSO:** Support for various SSO providers.
 - **_(coming soon)_ RBAC:** Role-based access control for managing user permissions.
 - **_(coming soon)_ Code host permission syncing:** Sync permissions from GitHub, Gitlab, etc. to Sourcebot.
 - **_(coming soon)_ Audit logs:** Audit logs for all actions performed on Sourcebot, such as user login, search, etc.
 </Accordion>
 <video
  autoPlay
  muted
  loop
  playsInline
  className="w-full aspect-video"
  src="https://framerusercontent.com/assets/t9Ci6NVULrcAG7u8hcBnR0Fnc.mp4"
 ></video>
 ### Self-hosted
 Sourcebot is designed to be easily self-hosted, allowing you to deploy it onto your own infrastructure, keeping your code private and secure.
 <Accordion title="Key benefits">
 - **Easy deployment:** Sourcebot is shipped as a [single docker container](https://github.com/sourcebot-dev/sourcebot/pkgs/container/sourcebot) that can be deployed to a k8s cluster, a VM, or any other platform that supports docker.
 - **Secure:** Your code **never** leaves your infrastructure.
 - **No-vendor lock-in:** Avoid dependency on a third-party SaaS provider; you can modify, extend, or migrate your deployment as needed.
 </Accordion>
 ## Get started
 ---
 <CardGroup cols={2}>
-  <Card horizontal title="Self-Host" icon="server" href="/self-hosting/overview">
+    <Card horizontal title="Deployment guide ->" href="/docs/deployment-guide" />
-    Deploy Sourcebot on your own infrastructure.
+    <Card horizontal title="Connecting your code ->" href="/docs/connections/overview" />
-  </Card>
+    <Card horizontal title="Search syntax reference ->" href="/docs/features/search/syntax-reference" />
-  <Card horizontal title="Sourcebot Cloud" icon="cloud" href="/docs/getting-started">
+    <Card horizontal title="Code navigation overview ->" href="/docs/features/code-navigation" />
    Use Sourcebot on our managed infrastructure.
  </Card>
 </CardGroup>
-We also have a [public demo](https://demo.sourcebot.dev) if you'd like to try Sourcebot out before registering.
+## Architecture
 ---
 Sourcebot is shipped as a single docker container that runs a collection of services using [supervisord](https://supervisord.org/):
 ![architecture diagram](/images/architecture_diagram.png)
 {/*TODO: outline the different services, how Sourcebot communicates with code hosts, and the different*/}
 Sourcebot consists of the following components:
 - **Web Server** : main Next.js web application serving the Sourcebot UI.
 - **Backend Worker** : Node.js process that incrementally syncs with code hosts (e.g., GitHub, GitLab etc.) and asynchronously indexes configured repositories.
 - **Zoekt** : the [open-source](https://github.com/sourcegraph/zoekt), trigram indexing code search engine that powers Sourcebot under the hood.
 - **Postgres** : transactional database for storing business-logic data.
 - **Redis Job Queue** : fast in-memory store. Used with [BullMQ](https://docs.bullmq.io/) for queuing asynchronous work.
 - **`.sourcebot/` cache** : file-system cache where persistent data is written.
 You can use managed Redis / Postgres services that run outside of the Sourcebot container by providing the `REDIS_URL` and `DATABASE_URL` environment variables, respectively. See the [environment variables](/docs/configuration/environment-variables) doc for more configuration options.
 ## Scalability
 ---
 One of our design philosophies for Sourcebot is to keep our infrastructure [radically simple](https://www.radicalsimpli.city/) while balancing scalability concerns. Depending on the number of repositories you have indexed and the instance you are running Sourcebot on, you may experience slow search times or other performance degradations. Our recommendation is to vertically scale your instance by increasing the number of CPU cores and memory.
 Sourcebot does not support horizontal scaling at this time, but it is on our roadmap. If this is something your team would be interested in, please contact us at [team@sourcebot.dev](mailto:team@sourcebot.dev).
 ## License key
 ---
 Sourcebot's core features are available under an [MIT license](https://github.com/sourcebot-dev/sourcebot/blob/HEAD/LICENSE) without any limits. Some [additional features](/docs/license-key#feature-availability) such as SSO and code navigation require a [license key](/docs/license-key).
 <CardGroup cols={2}>
    <Card title="Pricing page" href="https://www.sourcebot.dev/pricing" />
    <Card title="Request trial key" href="https://www.sourcebot.dev/contact" />
 </CardGroup>
 ## Telemetry
 ---
 By default, Sourcebot collects anonymized usage data through [PostHog](https://posthog.com/) to help us improve the performance and reliability of our tool. We don't collect or transmit <a href="https://demo.sourcebot.dev/~/search?query=captureEvent%5C(%20repo%3Asourcebot">any information related to your codebase</a>. In addition, all events are [sanitized](https://github.com/sourcebot-dev/sourcebot/blob/HEAD/packages/web/src/app/posthogProvider.tsx) to ensure that no sensitive details (ex. ip address, query info) leave your machine. 
 The data we collect includes general usage statistics and metadata such as query performance (e.g., search duration, error rates) to monitor the application's health and functionality. This information helps us better understand how Sourcebot is used and where improvements can be made.
 If you'd like to disable all telemetry, you can do so by setting the environment variable `SOURCEBOT_TELEMETRY_DISABLED` to `true`:
 ```bash
 docker run \
  -e SOURCEBOT_TELEMETRY_DISABLED=true \
  /* additional args */ \
  ghcr.io/sourcebot-dev/sourcebot:latest
 ```
 If you disabled telemetry correctly, you'll see the following log when starting Sourcebot:
 ```sh
 Disabling telemetry since SOURCEBOT_TELEMETRY_DISABLED was set.
 ```
--- a/docs/self-hosting/upgrade/v2-to-v3-guide.mdx
+++ b/docs/self-hosting/upgrade/v2-to-v3-guide.mdx
--- a/docs/self-hosting/upgrade/v3-to-v4-guide.mdx
+++ b/docs/self-hosting/upgrade/v3-to-v4-guide.mdx
@ -8,7 +8,7 @@ This guide will walk you through upgrading your Sourcebot deployment from v3 to
 <Warning>
 Please note that the following features are no longer supported in v4:
 - Multi-tenancy mode
- Unauthenticated access to a Sourcebot deployment - authentication is now built in by default. Unauthenticated access to a organization can be enabled with an unlimited seat [enterprise license](/self-hosting/license-key) 
+- Unauthenticated access to a Sourcebot deployment - authentication is now built in by default. Unauthenticated access to a organization can be enabled with an unlimited seat [enterprise license](/docs/license-key) 
 </Warning>
 ### If your deployment doesn't have authentication enabled
@ -22,12 +22,12 @@ Please note that the following features are no longer supported in v4:
        When you visit your new deployment you'll be presented with a sign-in page. Sourcebot now requires authentication, and all users must register and sign-in to the deployment.
        The first account that's registered will be made the owner. By default, you can register using basic credentials which will be stored encrypted within the postgres DB connected to Sourcebot. Check out
-        the [auth docs](/self-hosting/configuration/authentication) to setup additional auth providers.
+        the [auth docs](/docs/configuration/auth/overview) to setup additional auth providers.
        <img width="600" height="500" style={{ borderRadius: '0.5rem' }} src="/images/login_basic.png" />
    </Step>
    <Step title="(Optional) Configure transactional emails">
-        Emails can be sent on organization join request/approval by configuring [transactional emails](/self-hosting/configuration/transactional-emails)
+        Emails can be sent on organization join request/approval by configuring [transactional emails](/docs/configuration/transactional-emails)
        <img width="500" height="600" style={{ borderRadius: '0.5rem' }} src="/images/join_request_email.png" />
    </Step>
@ -36,7 +36,7 @@ Please note that the following features are no longer supported in v4:
        ![Pending Approval Page](/images/pending_approval.png)
-        The owner can view and approve join requests by navigating to **Settings -> Members**. Automatic provisioning of accounts is supported when using SSO/Oauth providers, check out the [auth docs](/self-hosting/configuration/authentication#enterprise-authentication-providers) for more info
+        The owner can view and approve join requests by navigating to **Settings -> Members**. Automatic provisioning of accounts is supported when using SSO/Oauth providers, check out the [auth docs](/docs/configuration/auth/overview#enterprise-authentication-providers) for more info
    </Step>
    <Step title="You're done!">
@ -47,11 +47,11 @@ Please note that the following features are no longer supported in v4:
 ### If your deployment has authentication enabled
 The only change that's required if your deployment has authentication enabled is to unset the `SOURCEBOT_AUTH_ENABLED` environment variable. New user registrations will now submit a request to join the organization which can be approved by the owner by 
-navigating to **Settings -> Members**. Emails can be sent on organization join request/approval by configuring [transactional emails](/self-hosting/configuration/transactional-emails)
+navigating to **Settings -> Members**. Emails can be sent on organization join request/approval by configuring [transactional emails](/docs/configuration/transactional-emails)
 ### If your deployment uses multi-tenancy mode
-Unfortunately, multi-tenancy mode is no longer officially supported in v4. To upgrade to v4, you'll need to unset the `SOURCEBOT_TENANCY_MODE` environment variable and wipe your Sourcebot cache. You can then follow the [instructions above](/self-hosting/upgrade/v3-to-v4-guide#if-your-deployment-doesnt-have-authentication-enabled)
+Unfortunately, multi-tenancy mode is no longer officially supported in v4. To upgrade to v4, you'll need to unset the `SOURCEBOT_TENANCY_MODE` environment variable and wipe your Sourcebot cache. You can then follow the [instructions above](/docs/upgrade/v3-to-v4-guide#if-your-deployment-doesnt-have-authentication-enabled)
 to finish upgrading to v4 in single-tenant mode.
 ## Troubleshooting
--- a/docs/images/bitbucket.png
+++ b/docs/images/bitbucket.png
--- a/docs/images/gerrit.png
+++ b/docs/images/gerrit.png
--- a/docs/images/git.png
+++ b/docs/images/git.png
--- a/docs/images/gitea.png
+++ b/docs/images/gitea.png
--- a/docs/images/github.png
+++ b/docs/images/github.png
--- a/docs/images/gitlab.png
+++ b/docs/images/gitlab.png
--- a/docs/images/local.png
+++ b/docs/images/local.png
--- a/docs/self-hosting/license-key.mdx
+++ b/docs/self-hosting/license-key.mdx
@ -1,26 +0,0 @@
 ---
 title: License key
 sidebarTitle: License key
 ---
 <Note>
 If you'd like a trial license, [reach out](https://www.sourcebot.dev/contact) and we'll send one over within 24 hours
 </Note>
 All core Sourcebot features are available in Sourcebot OSS (MIT Licensed). Some additional features require a license key. See the [pricing page](https://www.sourcebot.dev/pricing) for more details.
 ## Activating a license key
 After purchasing a license key, you can activate it by setting the `SOURCEBOT_EE_LICENSE_KEY` environment variable.
 ```bash
 docker run \
    -e SOURCEBOT_EE_LICENSE_KEY=<your-license-key> \
    /* additional args */ \
    ghcr.io/sourcebot-dev/sourcebot:latest
 ```
 ## Questions?
 If you have any questions regarding licensing, please [contact us](https://www.sourcebot.dev/contact).
--- a/docs/self-hosting/overview.mdx
+++ b/docs/self-hosting/overview.mdx
@ -1,139 +0,0 @@
 ---
 title: Self-host Sourcebot
 sidebarTitle: Overview
 ---
 import SupportedPlatforms from '/snippets/platform-support.mdx'
 <Note>Want a managed solution? Checkout [Sourcebot Cloud](/docs/getting-started).</Note>
 Sourcebot is open source and can be self-hosted using our official [Docker image](https://github.com/sourcebot-dev/sourcebot/pkgs/container/sourcebot).
 ## Quick Start Guide
 {/*@todo: record a self-hosting quick start guide
 <iframe
    width="560"
    height="315"
    src="https://www.youtube.com/embed/4KzFe50RQkQ"
    title="YouTube video player"
    frameborder="0"
    allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
    allowfullscreen
 ></iframe>
 */}
 <Steps>
    <Step title="Create a config">
        By default, Sourcebot requires a configuration file with a list of [code host connections](/docs/connections/overview) that specify what repositories should be **synced** (cloned and indexed). To get started, run the following command to create a starter `config.json`:
        ```bash
        touch config.json
        echo '{
            "$schema": "https://raw.githubusercontent.com/sourcebot-dev/sourcebot/main/schemas/v3/index.json",
            "connections": {
                // Comments are supported
                "starter-connection": {
                    "type": "github",
                    "repos": [
                        "sourcebot-dev/sourcebot"
                    ]
                }
            }
        }' > config.json
        ```
        This config creates a single GitHub connection named `starter-connection` that specifies [Sourcebot](https://github.com/sourcebot-dev/sourcebot) as a repo to sync.
    </Step>
    <Step title="Launch your instance">
        <Warning>If you're deploying Sourcebot behind a domain, you must set the [AUTH_URL](/self-hosting/configuration/environment-variables) environment variable</Warning>
        Sourcebot is packaged as a [single Docker image](https://github.com/sourcebot-dev/sourcebot/pkgs/container/sourcebot). In the same directory as `config.json`, run the following command to start your instance:
        ``` bash
        docker run \
            -p 3000:3000 \
            --pull=always \
            --rm \
            -v $(pwd):/data \
            -e CONFIG_PATH=/data/config.json \
            --name sourcebot \
            ghcr.io/sourcebot-dev/sourcebot:latest
        ```
        Navigate to `localhost:3000` to start searching the Sourcebot repo.
        <Accordion title="Details">
            **This command**:
                - pulls the latest version of the `sourcebot` docker image.
                - mounts the working directory to `/data` in the container to allow Sourcebot to persist data across restarts, and to access the `config.json`. In your local directory, you should see a `.sourcebot` folder created that contains all persistent data.
                - runs any pending database migrations.
                - starts up all services, including the webserver exposed on port 3000.
                - reads `config.json` and starts syncing.
        </Accordion>
        <Note>Hit an issue? Please let us know on [GitHub discussions](https://github.com/sourcebot-dev/sourcebot/discussions/categories/support) or by [emailing us](mailto:team@sourcebot.dev).</Note>
    </Step>
    <Step title="Create the owner account">
        Sourcebot has built-in authentication which gates your instance. The first account which is registered on a fresh Sourcebot deployment is made owner.
        Registration is performed using basic credentials which are stored encrypted within your deployment. To setup more authentication providers
        check out the [auth docs](/self-hosting/configuration/authentication)
        <img width="600" height="500" style={{ borderRadius: '0.5rem' }} src="/images/login_basic.png" />
    </Step>
    <Step title="Link your code">
        Sourcebot supports indexing public & private code on the following code hosts:
        <SupportedPlatforms />
        <Note>Missing your code host? [Submit a feature request on GitHub](https://github.com/sourcebot-dev/sourcebot/discussions/categories/ideas).</Note>
    </Step>
 </Steps>
 ## Architecture
 Sourcebot is shipped as a single docker container that runs a collection of services using [supervisord](https://supervisord.org/):
 ![architecture diagram](/images/architecture_diagram.png)
 {/*TODO: outline the different services, how Sourcebot communicates with code hosts, and the different*/}
 Sourcebot consists of the following components:
 - **Web Server** : main Next.js web application serving the Sourcebot UI.
 - **Backend Worker** : Node.js process that incrementally syncs with code hosts (e.g., GitHub, GitLab etc.) and asynchronously indexes configured repositories.
 - **Zoekt** : the [open-source](https://github.com/sourcegraph/zoekt), trigram indexing code search engine that powers Sourcebot under the hood.
 - **Postgres** : transactional database for storing business-logic data.
 - **Redis Job Queue** : fast in-memory store. Used with [BullMQ](https://docs.bullmq.io/) for queuing asynchronous work.
 - **`.sourcebot/` cache** : file-system cache where persistent data is written.
 You can use managed Redis / Postgres services that run outside of the Sourcebot container by providing the `REDIS_URL` and `DATABASE_URL` environment variables, respectively. See the [configuration](/self-hosting/configuration) for more configuration options.
 ## Scalability
 One of our design philosophies for Sourcebot is to keep our infrastructure [radically simple](https://www.radicalsimpli.city/) while balancing scalability concerns. Depending on the number of repositories you have indexed and the instance you are running Sourcebot on, you may experience slow search times or other performance degradations. Our recommendation is to vertically scale your instance by increasing the number of CPU cores and memory.
 Sourcebot does not support horizontal scaling at this time, but it is on our roadmap. If this is something your team would be interested in, please contact us at [team@sourcebot.dev](mailto:team@sourcebot.dev).
 ## Telemetry
 By default, Sourcebot collects anonymized usage data through [PostHog](https://posthog.com/) to help us improve the performance and reliability of our tool. We don't collect or transmit <a href="https://demo.sourcebot.dev/~/search?query=captureEvent%5C(%20repo%3Asourcebot">any information related to your codebase</a>. In addition, all events are [sanitized](https://github.com/sourcebot-dev/sourcebot/blob/HEAD/packages/web/src/app/posthogProvider.tsx) to ensure that no sensitive details (ex. ip address, query info) leave your machine. 
 The data we collect includes general usage statistics and metadata such as query performance (e.g., search duration, error rates) to monitor the application's health and functionality. This information helps us better understand how Sourcebot is used and where improvements can be made.
 If you'd like to disable all telemetry, you can do so by setting the environment variable `SOURCEBOT_TELEMETRY_DISABLED` to `true`:
 ```bash
 docker run \
  -e SOURCEBOT_TELEMETRY_DISABLED=true \
  /* additional args */ \
  ghcr.io/sourcebot-dev/sourcebot:latest
 ```
 If you disabled telemetry correctly, you'll see the following log when starting Sourcebot:
 ```sh
 Disabling telemetry since SOURCEBOT_TELEMETRY_DISABLED was set.
 ```
--- a/docs/snippets/bitbucket-app-password.mdx
+++ b/docs/snippets/bitbucket-app-password.mdx
@ -1,6 +1,6 @@
 <Tabs>
    <Tab title="Environment Variable">
-        <Note>Environment variables are only supported in a [declarative config](/self-hosting/configuration/declarative-config) and cannot be used in the web UI.</Note>
+        <Note>Environment variables are only supported in a [declarative config](/docs/configuration/declarative-config) and cannot be used in the web UI.</Note>
        1. Add the `token` and `user` (username associated with the app password you created) properties to your connection config:
        ```json
@ -27,7 +27,7 @@
    </Tab>
    <Tab title="Secret">
-        <Note>Secrets are only supported when [authentication](/self-hosting/configuration/authentication) is enabled.</Note>
+        <Note>Secrets are only supported when [authentication](/docs/configuration/auth/overview) is enabled.</Note>
        1. Navigate to **Secrets** in settings and create a new secret with your access token:
--- a/docs/snippets/bitbucket-token.mdx
+++ b/docs/snippets/bitbucket-token.mdx
@ -1,6 +1,6 @@
 <Tabs>
    <Tab title="Environment Variable">
-        <Note>Environment variables are only supported in a [declarative config](/self-hosting/configuration/declarative-config) and cannot be used in the web UI.</Note>
+        <Note>Environment variables are only supported in a [declarative config](/docs/configuration/declarative-config) and cannot be used in the web UI.</Note>
        1. Add the `token` property to your connection config:
        ```json
@ -25,7 +25,7 @@
    </Tab>
    <Tab title="Secret">
-        <Note>Secrets are only supported when [authentication](/self-hosting/configuration/authentication) is enabled.</Note>
+        <Note>Secrets are only supported when [authentication](/docs/configuration/auth/overview) is enabled.</Note>
        1. Navigate to **Secrets** in settings and create a new secret with your PAT:
--- a/docs/snippets/license-key-required.mdx
+++ b/docs/snippets/license-key-required.mdx
@ -0,0 +1,4 @@
 <Note>
 This feature is only available with an active Enterprise license. Please add your [license key](/docs/license-key) to activate it.
 </Note>
--- a/docs/snippets/schemas/v3/index.schema.mdx
+++ b/docs/snippets/schemas/v3/index.schema.mdx
@ -188,7 +188,7 @@
    },
    "contexts": {
      "type": "object",
-      "description": "[Sourcebot EE] Defines a collection of search contexts. This is only available in single-tenancy mode. See: https://docs.sourcebot.dev/docs/search/search-contexts",
+      "description": "[Sourcebot EE] Defines a collection of search contexts. This is only available in single-tenancy mode. See: https://docs.sourcebot.dev/docs/features/search/search-contexts",
      "patternProperties": {
        "^[a-zA-Z0-9_-]+$": {
          "$schema": "http://json-schema.org/draft-07/schema#",
--- a/packages/mcp/README.md
+++ b/packages/mcp/README.md
@ -2,7 +2,7 @@
 [![Sourcebot](https://img.shields.io/badge/Website-sourcebot.dev-blue)](https://sourcebot.dev)
 [![GitHub](https://img.shields.io/badge/GitHub-sourcebot--dev%2Fsourcebot-green?logo=github)](https://github.com/sourcebot-dev/sourcebot)
-[![Docs](https://img.shields.io/badge/Docs-docs.sourcebot.dev-yellow)](https://docs.sourcebot.dev/docs/more/mcp-server)
+[![Docs](https://img.shields.io/badge/Docs-docs.sourcebot.dev-yellow)](https://docs.sourcebot.dev/docs/features/mcp-server)
 [![npm](https://img.shields.io/npm/v/@sourcebot/mcp)](https://www.npmjs.com/package/@sourcebot/mcp)
 The Sourcebot MCP server gives your LLM agents the ability to fetch code context across thousands of repos hosted on [GitHub](https://docs.sourcebot.dev/docs/connections/github), [GitLab](https://docs.sourcebot.dev/docs/connections/gitlab), [BitBucket](https://docs.sourcebot.dev/docs/connections/bitbucket-cloud) and [more](#supported-code-hosts). Ask your LLM a question, and the Sourcebot MCP server will fetch relevant context from its index and inject it into your chat session. Some use cases this unlocks include:
@ -159,7 +159,7 @@ The Sourcebot MCP server gives your LLM agents the ability to fetch code context
 <br/>
-For a more detailed guide, checkout [the docs](https://docs.sourcebot.dev/docs/more/mcp-server).
+For a more detailed guide, checkout [the docs](https://docs.sourcebot.dev/docs/features/mcp-server).
 ## Available Tools
--- a/packages/schemas/src/v3/index.schema.ts
+++ b/packages/schemas/src/v3/index.schema.ts
@ -187,7 +187,7 @@ const schema = {
    },
    "contexts": {
      "type": "object",
-      "description": "[Sourcebot EE] Defines a collection of search contexts. This is only available in single-tenancy mode. See: https://docs.sourcebot.dev/docs/search/search-contexts",
+      "description": "[Sourcebot EE] Defines a collection of search contexts. This is only available in single-tenancy mode. See: https://docs.sourcebot.dev/docs/features/search/search-contexts",
      "patternProperties": {
        "^[a-zA-Z0-9_-]+$": {
          "$schema": "http://json-schema.org/draft-07/schema#",
--- a/packages/schemas/src/v3/index.type.ts
+++ b/packages/schemas/src/v3/index.type.ts
@ -16,7 +16,7 @@ export interface SourcebotConfig {
  $schema?: string;
  settings?: Settings;
  /**
-   * [Sourcebot EE] Defines a collection of search contexts. This is only available in single-tenancy mode. See: https://docs.sourcebot.dev/docs/search/search-contexts
+   * [Sourcebot EE] Defines a collection of search contexts. This is only available in single-tenancy mode. See: https://docs.sourcebot.dev/docs/features/search/search-contexts
   */
  contexts?: {
    [k: string]: SearchContext;
--- a/packages/web/src/app/[domain]/agents/page.tsx
+++ b/packages/web/src/app/[domain]/agents/page.tsx
@ -9,7 +9,7 @@ const agents = [
    name: "Review Agent",
    description: "An AI code review agent that reviews your PRs. Uses the code indexed on Sourcebot to provide codebase-wide context.",
    requiredEnvVars: ["GITHUB_APP_ID", "GITHUB_APP_WEBHOOK_SECRET", "GITHUB_APP_PRIVATE_KEY_PATH", "OPENAI_API_KEY"],
-    configureUrl: "https://docs.sourcebot.dev/docs/agents/review-agent"
+    configureUrl: "https://docs.sourcebot.dev/docs/features/agents/review-agent"
  },
 ];
--- a/packages/web/src/app/[domain]/browse/components/bottomPanel.tsx
+++ b/packages/web/src/app/[domain]/browse/components/bottomPanel.tsx
@ -18,7 +18,7 @@ import { useRouter } from "next/navigation";
 export const BOTTOM_PANEL_MIN_SIZE = 35;
 export const BOTTOM_PANEL_MAX_SIZE = 65;
-const CODE_NAV_DOCS_URL = "https://docs.sourcebot.dev/docs/search/code-navigation";
+const CODE_NAV_DOCS_URL = "https://docs.sourcebot.dev/docs/features/code-navigation";
 export const BottomPanel = () => {
    const panelRef = useRef<ImperativePanelHandle>(null);
--- a/packages/web/src/app/[domain]/settings/license/page.tsx
+++ b/packages/web/src/app/[domain]/settings/license/page.tsx
@ -33,7 +33,7 @@ export default async function LicensePage({ params: { domain } }: LicensePagePro
                    <Info className="h-12 w-12 text-muted-foreground mb-4" />
                    <h3 className="text-lg font-medium mb-2">No License Found</h3>
                    <p className="text-sm text-muted-foreground text-center max-w-md mb-6">
-                        Check out the <a href="https://docs.sourcebot.dev/self-hosting/license-key" target="_blank" rel="noopener noreferrer" className="text-primary">docs</a> for more information.
+                        Check out the <a href="https://docs.sourcebot.dev/docs/license-key" target="_blank" rel="noopener noreferrer" className="text-primary">docs</a> for more information.
                    </p>
                    <div className="mb-8 max-w-md rounded-lg bg-slate-50 p-4 dark:bg-slate-800">
                        <p className="text-base text-center">
--- a/packages/web/src/app/login/components/loginForm.tsx
+++ b/packages/web/src/app/login/components/loginForm.tsx
@ -1,9 +1,8 @@
 'use client';
 import { Button } from "@/components/ui/button";
 import Image from "next/image";
 import { signIn } from "next-auth/react";
-import { Fragment, useCallback, useMemo } from "react";
+import { Fragment, useCallback, useMemo, useState } from "react";
 import { Card } from "@/components/ui/card";
 import { cn, getAuthProviderInfo } from "@/lib/utils";
 import { MagicLinkForm } from "./magicLinkForm";
@ -14,6 +13,7 @@ import useCaptureEvent from "@/hooks/useCaptureEvent";
 import DemoCard from "@/app/[domain]/onboard/components/demoCard";
 import Link from "next/link";
 import { env } from "@/env.mjs";
 import { LoadingButton } from "@/components/ui/loading-button";
 const TERMS_OF_SERVICE_URL = "https://sourcebot.dev/terms";
 const PRIVACY_POLICY_URL = "https://sourcebot.dev/privacy";
@ -27,7 +27,9 @@ interface LoginFormProps {
 export const LoginForm = ({ callbackUrl, error, providers }: LoginFormProps) => {
    const captureEvent = useCaptureEvent();
    const onSignInWithOauth = useCallback((provider: string) => {
-        signIn(provider, { redirectTo: callbackUrl ?? "/" });
+        signIn(provider, {
            redirectTo: callbackUrl ?? "/"
        });
    }, [callbackUrl]);
    const errorMessage = useMemo(() => {
@ -137,15 +139,21 @@ const ProviderButton = ({
    onClick: () => void;
    className?: string;
 }) => {
    const [isLoading, setIsLoading] = useState(false);
    return (
-        <Button
+        <LoadingButton
-            onClick={onClick}
+            onClick={() => {
                setIsLoading(true);
                onClick();
            }}
            className={cn("w-full", className)}
            variant="outline"
            loading={isLoading}
        >
            {logo && <Image src={logo.src} alt={name} className={cn("w-5 h-5 mr-2", logo.className)} />}
            Sign in with {name}
-        </Button>
+        </LoadingButton>
    )
 }
--- a/packages/web/src/env.mjs
+++ b/packages/web/src/env.mjs
@ -26,20 +26,26 @@ export const env = createEnv({
        // Enterprise Auth
        AUTH_EE_ENABLE_JIT_PROVISIONING: booleanSchema.default('false'),
        AUTH_EE_GITHUB_CLIENT_ID: z.string().optional(),
        AUTH_EE_GITHUB_CLIENT_SECRET: z.string().optional(),
        AUTH_EE_GITHUB_BASE_URL: z.string().optional(),
        AUTH_EE_GITLAB_CLIENT_ID: z.string().optional(),
        AUTH_EE_GITLAB_CLIENT_SECRET: z.string().optional(),
        AUTH_EE_GITLAB_BASE_URL: z.string().default("https://gitlab.com"),
        AUTH_EE_GOOGLE_CLIENT_ID: z.string().optional(),
        AUTH_EE_GOOGLE_CLIENT_SECRET: z.string().optional(),
        AUTH_EE_OKTA_CLIENT_ID: z.string().optional(),
        AUTH_EE_OKTA_CLIENT_SECRET: z.string().optional(),
        AUTH_EE_OKTA_ISSUER: z.string().optional(),
        AUTH_EE_KEYCLOAK_CLIENT_ID: z.string().optional(),
        AUTH_EE_KEYCLOAK_CLIENT_SECRET: z.string().optional(),
        AUTH_EE_KEYCLOAK_ISSUER: z.string().optional(),
        AUTH_EE_MICROSOFT_ENTRA_ID_CLIENT_ID: z.string().optional(),
        AUTH_EE_MICROSOFT_ENTRA_ID_CLIENT_SECRET: z.string().optional(),
        AUTH_EE_MICROSOFT_ENTRA_ID_ISSUER: z.string().optional(),
--- a/packages/web/src/features/entitlements/server.ts
+++ b/packages/web/src/features/entitlements/server.ts
@ -55,7 +55,6 @@ export const getPlan = (): Plan => {
        return licenseKey.seats === SOURCEBOT_UNLIMITED_SEATS ? "self-hosted:enterprise-unlimited" : "self-hosted:enterprise";
    } else {
        console.info(`No valid license key found. Falling back to oss plan.`);
        return "oss"; 
    }
 }
--- a/packages/web/src/lib/newsData.ts
+++ b/packages/web/src/lib/newsData.ts
@ -5,18 +5,18 @@ export const newsData: NewsItem[] = [
    unique_id: "code-nav",
    header: "Code navigation",
    sub_header: "Built in go-to definition and find references",
-    url: "https://docs.sourcebot.dev/docs/search/code-navigation"
+    url: "https://docs.sourcebot.dev/docs/features/code-navigation"
  },
  {
    unique_id: "sso",
    header: "SSO",
    sub_header: "We've added support for SSO providers",
-    url: "https://docs.sourcebot.dev/self-hosting/configuration/authentication",
+    url: "https://docs.sourcebot.dev/docs/configuration/auth/overview",
  },
  {
    unique_id: "search-contexts",
    header: "Search contexts",
    sub_header: "Filter searches by groups of repos",
-    url: "https://docs.sourcebot.dev/docs/search/search-contexts"
+    url: "https://docs.sourcebot.dev/docs/features/search/search-contexts"
  }
 ]; 
--- a/schemas/v3/index.json
+++ b/schemas/v3/index.json
@ -83,7 +83,7 @@
        },
        "contexts": {
            "type": "object",
-            "description": "[Sourcebot EE] Defines a collection of search contexts. This is only available in single-tenancy mode. See: https://docs.sourcebot.dev/docs/search/search-contexts",
+            "description": "[Sourcebot EE] Defines a collection of search contexts. This is only available in single-tenancy mode. See: https://docs.sourcebot.dev/docs/features/search/search-contexts",
            "patternProperties": {
                "^[a-zA-Z0-9_-]+$": {
                    "$ref": "#/definitions/SearchContext"