docs: v5 docs updates

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: msukkari

docs/api-reference/sourcebot-public.openapi.json

@@ -2289,7 +2289,7 @@
         "summary": "Get a user",
         "description": "Fetches profile details for a single organization member by `userId`. Only organization owners can access this endpoint.",
         "x-mint": {
-          "content": "<Note>\nThis API is only available with an active Enterprise license. Please add your [license key](/docs/license-key) to activate it.\n</Note>"
+          "content": "<Note>\nThis API is only available with an active Enterprise license. Please add your [license key](/docs/activating-a-subscription) to activate it.\n</Note>"
         },
         "parameters": [
           {
@@ -2364,7 +2364,7 @@
         "summary": "Delete a user",
         "description": "Permanently deletes a user and all associated records. Only organization owners can delete other users.",
         "x-mint": {
-          "content": "<Note>\nThis API is only available with an active Enterprise license. Please add your [license key](/docs/license-key) to activate it.\n</Note>"
+          "content": "<Note>\nThis API is only available with an active Enterprise license. Please add your [license key](/docs/activating-a-subscription) to activate it.\n</Note>"
         },
         "parameters": [
           {
@@ -2441,7 +2441,7 @@
         "summary": "List users",
         "description": "Returns all members of the organization. Only organization owners can access this endpoint.",
         "x-mint": {
-          "content": "<Note>\nThis API is only available with an active Enterprise license. Please add your [license key](/docs/license-key) to activate it.\n</Note>"
+          "content": "<Note>\nThis API is only available with an active Enterprise license. Please add your [license key](/docs/activating-a-subscription) to activate it.\n</Note>"
         },
         "responses": {
           "200": {
@@ -2486,7 +2486,7 @@
         "summary": "List audit records",
         "description": "Returns a paginated list of audit log entries. Only organization owners can access this endpoint.",
         "x-mint": {
-          "content": "<Note>\nThis API is only available with an active Enterprise license. Please add your [license key](/docs/license-key) to activate it.\n</Note>"
+          "content": "<Note>\nThis API is only available with an active Enterprise license. Please add your [license key](/docs/activating-a-subscription) to activate it.\n</Note>"
         },
         "parameters": [
           {

docs/docs.json

@@ -40,18 +40,10 @@
                         "pages": [
                             "docs/overview",
                             {
-                                "group": "Deployment",
+                                "group": "Deploy Sourcebot",
                                 "pages": [
                                     "docs/deployment/docker-compose",
-                                    "docs/deployment/k8s",
-                                    "docs/deployment/sizing-guide",
-                                    {
-                                        "group": "Infrastructure",
-                                        "pages": [
-                                            "docs/deployment/infrastructure/architecture",
-                                            "docs/deployment/infrastructure/redis"
-                                        ]
-                                    }
+                                    "docs/deployment/k8s"
                                 ]
                             }
                         ]
@@ -61,8 +53,8 @@
                         "pages": [
                             {
                                 "group": "Code Search",
+                                "root": "docs/features/search/code-search",
                                 "pages": [
-                                    "docs/features/search/overview",
                                     "docs/features/search/syntax-reference",
                                     "docs/features/search/ai-search-assist",
                                     "docs/features/search/multi-branch-indexing",
@@ -71,8 +63,8 @@
                             },
                             {
                                 "group": "Ask Sourcebot",
+                                "root": "docs/features/ask/ask-sourcebot",
                                 "pages": [
-                                    "docs/features/ask/overview",
                                     "docs/features/ask/chat-sharing",
                                     "docs/features/ask/add-model-providers"
                                 ]
@@ -84,8 +76,8 @@
                             {
                                 "group": "Agents",
                                 "tag": "experimental",
+                                "root": "docs/features/agents/agents",
                                 "pages": [
-                                    "docs/features/agents/overview",
                                     "docs/features/agents/review-agent"
                                 ]
                             }
@@ -98,8 +90,8 @@
                             "docs/configuration/environment-variables",
                             {
                                 "group": "Indexing your code",
+                                "root": "docs/connections/indexing-your-code",
                                 "pages": [
-                                    "docs/connections/overview",
                                     "docs/connections/github",
                                     "docs/connections/gitlab",
                                     "docs/connections/bitbucket-cloud",
@@ -117,24 +109,48 @@
                             "docs/configuration/idp",
                             {
                                 "group": "Authentication",
+                                "root": "docs/configuration/auth/authentication",
                                 "pages": [
-                                    "docs/configuration/auth/overview",
                                     "docs/configuration/auth/providers",
                                     "docs/configuration/auth/access-settings",
                                     "docs/configuration/auth/roles-and-permissions",
                                     "docs/configuration/auth/faq"
                                 ]
                             },
-                            "docs/license-key",
-                            "docs/billing",
                             "docs/configuration/transactional-emails",
                             "docs/configuration/structured-logging",
                             "docs/configuration/audit-logs"
                         ]
                     },
+                    {
+                        "group": "Subscribe",
+                        "pages": [
+                            "docs/activating-a-subscription",
+                            "docs/billing",
+                            "docs/free-trial"
+                        ]
+                    },
+                    {
+                        "group": "Misc",
+                        "pages": [
+                            "docs/misc/architecture",
+                            "docs/misc/scalability",
+                            "docs/misc/telemetry",
+                            "docs/misc/service-ping",
+                            "docs/deployment/sizing-guide",
+                            {
+                                "group": "Infrastructure",
+                                "pages": [
+                                    "docs/deployment/infrastructure/architecture",
+                                    "docs/deployment/infrastructure/redis"
+                                ]
+                            }
+                        ]
+                    },
                     {
                         "group": "Upgrade",
                         "pages": [
+                            "docs/upgrade/v4-to-v5-guide",
                             "docs/upgrade/v3-to-v4-guide",
                             "docs/upgrade/v2-to-v3-guide"
                         ]
@@ -231,5 +247,31 @@
     "appearance": {
         "default": "dark",
         "strict": false
-    }
+    },
+    "redirects": [
+        {
+            "source": "/docs/features/search/overview",
+            "destination": "/docs/features/search/code-search"
+        },
+        {
+            "source": "/docs/features/ask/overview",
+            "destination": "/docs/features/ask/ask-sourcebot"
+        },
+        {
+            "source": "/docs/features/agents/overview",
+            "destination": "/docs/features/agents/agents"
+        },
+        {
+            "source": "/docs/connections/overview",
+            "destination": "/docs/connections/indexing-your-code"
+        },
+        {
+            "source": "/docs/configuration/auth/overview",
+            "destination": "/docs/configuration/auth/authentication"
+        },
+        {
+            "source": "/docs/license-key",
+            "destination": "/docs/activating-a-subscription"
+        }
+    ]
 }

docs/docs/activating-a-subscription.mdx

@@ -0,0 +1,39 @@
+---
+title: Activating a Subscription
+sidebarTitle: Activating a subscription
+---
+
+You can activate a paid plan subscription by using either an Activation Code or a License Key.
+
+# Activation Code (Online Licensing)
+
+<Warning>Your Sourcebot deployment must be able to send a [Service Ping](/docs/misc/service-ping) to validate your Activation Code. If your deployment is unable to send a service ping for 7 days it will downgrade to the free plan until a successul ping is sent. </Warning>
+
+The default mechanism for activating a subscription is through an Activation Code. This activation mechanism allows your Sourcebot deployment to automatically manage its subscription by regularly
+sychronizing with our license server.
+
+### What data does Sourcebot collect?
+
+To enable online licensing, your Sourcebot deployment must be able to communicate with our license server through our [Service Ping](/docs/misc/service-ping). The data that is transmitted is limited to information that is
+required to administer your Sourcebot license and support dynamic seat increases. No sensitive data (source code, AI inputs/outputs, credentials, or user information) will ever be transmitted. For more information, please check out our [privacy policy](https://www.sourcebot.dev/privacy)
+
+# License Key (Offline Licensing)
+
+<Note>The default mechanism for activating a subscription is now through an [Activation Code](#activation-code-online-licensing). Offline licensing using a License Key may be requested by reaching out using our enterprise contact form on our [pricing page](https://www.sourcebot.dev/pricing)</Note>
+
+After purchasing a license key, you can activate it by setting the `SOURCEBOT_EE_LICENSE_KEY` environment variable. 
+
+If you'd like to increase the number of seats on your Sourcebot deployment you must request a new license key, manually update this environment variable, and then restart your deployment.
+
+```bash
+docker run \
+    -e SOURCEBOT_EE_LICENSE_KEY=<your-license-key> \
+    /* additional args */ \
+    ghcr.io/sourcebot-dev/sourcebot:latest
+```
+
+## FAQ
+
+#### What happens when my subscription expires?
+
+When a paid plan subscription expires, your deployment will automatically be downgraded to the free plan. You must upgrade your subscription in order to continue using the paid features.

docs/docs/billing.mdx

@@ -1,23 +1,27 @@
 ---
-title: Billing
-sidebarTitle: Billing
+title: Seat Reconciliation 
+sidebarTitle: Seat Reconciliation 
 ---
 
-Sourcebot Enterprise is available on monthly and yearly plans. Both are seat-based. This page explains how seats are billed, how changes mid-term are handled, and what happens at renewal.
+When using an [Activation Code](/docs/activating-a-subscription#activation-code-online-licensing), your Sourcebot deployment is permitted to exceed the number of seats you've purchsed. Seat reconciliation refers
+to how these excess seats are billed, and it depends on your billing period. 
 
-## Seat count
-Your seat count is the number of active users in your Sourcebot instance. Seat usage is reported to Sourcebot on a daily interval, and your subscription quantity is kept in sync with that number.
+<Note>Seat reconciliation doesn't apply if you're using a [License Key](/docs/activating-a-subscription#license-key-offline-licensing) since the key sets a hard cap on seats. If you're using a license key and would like more seats, please reach out to us to purchase a new license key.</Note>
 
-## Monthly plans
-Monthly subscriptions are billed at the start of each billing cycle. Users added mid-cycle are prorated across the remaining days and appear on your next invoice. Users removed mid-cycle take effect at the next cycle. There is no refund for the remainder of the current one.
+For a more detailed breakdown, please refer to our [Software License Agreeement](https://www.sourcebot.dev/terms) which is the source of truth on how seats are handled and billed.
 
-In short: you can scale up at any time and pay the prorated difference. Scaling down is effectively free until the cycle rolls over.
+# Monthly Billing
 
-## Yearly plans
+Sourcebot supports monthly with standard proration behavior. Users added during the month are prorated across the remaining days and appear on your next invoice. Users removed during the month take effect at the next cycle, and are not refunded for the current cycle.
+
+# Yearly Billing
+
+## Quarterly Reconciliation
+The standard mechanism for seat reconciliation in yearly plans is through quarterly reconciliation. You are billed per quarter on a prorated basis for the remaining portion of your subscription term for any additional seats you activate.
+
+To prevent overages, you can restrict you may register on your Sourcebot deployment through our [access controls](/docs/configuration/auth/access-settings).
 
-Yearly subscriptions are billed upfront for a committed seat count. As users are added during the term, the seat count rises but you aren't charged immediately. Every three months we reconcile. Any seats added that quarter are billed, prorated across the quarters remaining in the term.
 
-Seats only move upward during the term. Shrinking the user count does not refund, and does not reduce the seat count until renewal. At renewal, you're invoiced at your current seat count, and that number becomes the committed baseline for the next year.
 
 ### Example
 

docs/docs/configuration/audit-logs.mdx

@@ -5,7 +5,7 @@ sidebarTitle: Audit logs
 
 import LicenseKeyRequired from '/snippets/license-key-required.mdx'
 
-<LicenseKeyRequired feature="Audit Logs" />
+<LicenseKeyRequired feature="Audit Logs" verb="are" />
 
 Audit logs are a collection of notable events performed by users within a Sourcebot deployment. Each audit log records information on the action taken, the user who performed the 
 action, and when the action took place. 
@@ -19,7 +19,7 @@ Audit logs are enabled by default and can be controlled with the `SOURCEBOT_EE_A
 By default, audit logs older than 180 days are automatically pruned daily. You can configure the retention period using the `SOURCEBOT_EE_AUDIT_RETENTION_DAYS` [environment variable](/docs/configuration/environment-variables). Set it to `0` to disable automatic pruning and retain logs indefinitely.
 
 ## Fetching Audit Logs
-Audit logs are stored in the [postgres database](/docs/overview#architecture) connected to Sourcebot. To fetch all of the audit logs, you can use the following API:
+Audit logs are stored in the [postgres database](/docs/misc/architecture) connected to Sourcebot. To fetch all of the audit logs, you can use the following API:
 
 ```bash icon="terminal" Fetch audit logs
 curl --request GET '$SOURCEBOT_URL/api/ee/audit' \

docs/docs/configuration/auth/overview.mdx …cs/configuration/auth/authentication.mdxdocs/docs/configuration/auth/overview.mdx renamed to docs/docs/configuration/auth/authentication.mdx docs/docs/configuration/auth/overview.mdx renamed to docs/docs/configuration/auth/authentication.mdx

@@ -1,5 +1,5 @@
 ---
-title: Overview
+title: Authentication
 ---
 
 <Warning>If you're deploying Sourcebot behind a domain, you must set the [AUTH_URL](/docs/configuration/environment-variables) environment variable.</Warning>

docs/docs/configuration/auth/providers.mdx

@@ -27,4 +27,4 @@ See [transactional emails](/docs/configuration/transactional-emails) for more de
 # Enterprise Authentication Providers
 
 Sourcebot supports authentication using several different [external identity providers](/docs/configuration/idp) as well. These identity providers require an
-[enterprise license](/docs/license-key)
+[enterprise license](/docs/activating-a-subscription)

docs/docs/configuration/config-file.mdx

@@ -23,7 +23,7 @@ The config file tells Sourcebot which repos to index, what language models to us
 
 The config file you provide Sourcebot must follow the [schema](https://github.com/sourcebot-dev/sourcebot/blob/main/schemas/v3/index.json). This schema consists of the following properties:
 
-- [Connections](/docs/connections/overview) (`connections`): Defines a set of connections that tell Sourcebot which repos to index and from where
+- [Connections](/docs/connections/indexing-your-code) (`connections`): Defines a set of connections that tell Sourcebot which repos to index and from where
 - [Language Models](/docs/configuration/language-model-providers) (`models`): Defines a set of language model providers for use with [Ask Sourcebot](/docs/features/ask)
 - [Settings](#settings) (`settings`): Additional settings to tweak your Sourcebot deployment
 - [Search Contexts](/docs/features/search/search-contexts) (`contexts`): Groupings of repos that you can search against

docs/docs/configuration/declarative-config.mdx

@@ -5,7 +5,7 @@ sidebarTitle: Declarative config
 
 import ConfigSchema from '/snippets/schemas/v3/index.schema.mdx'
 
-Some teams require Sourcebot to be configured via a file (where it can be stored in version control, run through CI/CD pipelines, etc.) instead of a web UI. For more information on configuring connections, see this [overview](/docs/connections/overview).
+Some teams require Sourcebot to be configured via a file (where it can be stored in version control, run through CI/CD pipelines, etc.) instead of a web UI. For more information on configuring connections, see this [overview](/docs/connections/indexing-your-code).
 
 
 | Variable | Description |