diff --git a/docs/apps/build-plane-app.mdx b/docs/apps/build-plane-app.mdx
new file mode 100644
index 0000000..8baf13a
--- /dev/null
+++ b/docs/apps/build-plane-app.mdx
@@ -0,0 +1,379 @@
+---
+title: Build a Plane App (BYOA)
+sidebar_label: App development
+description: Step-by-step development guide to build and integrate an app with Plane using OAuth-based authentication and authorization workflow.
+
+siderbar_position: 2
+---
+
+import Tabs from "@theme/Tabs";
+import TabItem from "@theme/TabItem";
+
+{frontMatter.description && (
+
+
{frontMatter.description}
+)}
+
+:::info
+Plane apps are currently in **Beta**. Please send any feedback to support@plane.so.
+:::
+
+## Introduction
+Plane apps seamlessly integrate tools and services with Plane so you can
+use them without ever leaving your Workspace. Apps are conveniently available
+from our [marketplace](https://plane.so/marketplace/integrations), helping you
+stay focused and productive.
+
+## Why Build a Plane App?
+
+**Stop doing manual work.**
+Plane integrations eliminate repetitive tasks like copying updates between
+tools, creating work items from support tickets, and generating status reports.
+Instead of spending hours on administrative work, let your app handle it
+automatically.
+
+**Connect everything you already use.**
+Your team probably uses dozens of different tools. Plane apps create a unified
+workflow by connecting your favorite CRM, time tracking app, CI/CD pipelines,
+communication tools, and more, together into Plane. One change in Plane can
+trigger updates across your entire tech stack.
+
+**Build exactly what you need.**
+Unlike rigid SaaS platforms, Plane's open core nature means you can create
+integrations that fit your specific workflow.
+
+## Prerequisites
+
+- A [Plane](https://app.plane.so) workspace
+- Admin access to your workspace settings
+- Familiarity with OAuth 2.0 concepts (authorization code flow)
+- A backend server to handle OAuth token exchange
+
+## High-Level Workflow
+
+1. [Register your app on Plane developer portal](/apps/build-plane-app/#registering-your-app)
+2. [Implement OAuth flow](/apps/build-plane-app#implement-oauth-flow)
+3. [Obtain and store access tokens securely](/apps/build-plane-app#obtain-and-store-access-tokens-securely)
+4. [Make authenticated API requests to Plane](/apps/build-plane-app#make-authenticated-api-requests-to-plane)
+5. [Handle token refresh](/apps/build-plane-app#handle-token-refresh)
+
+## Registering Your App
+
+To build an OAuth application with Plane:
+
+1. Navigate to `https://app.plane.so//settings/applications/`.
+2. Click on the **Build your own** button.
+3. Fill out the form with the required details:
+
+ - **Redirect URIs**: Provide the URIs where Plane will send the authorization code after the user consents to the app.
+ - **Contact Details**: Add your email or other contact information.
+ - **Setup URL(Optional)**: Provide the URL that users will be redirected to when they click "Install App" from the marketplace. This URL should initiate the OAuth flow for your application.
+ - **Webhook URL Endpoint(Optional)**: Your service's webhook endpoint. Plane will send an HTTP `POST` request to this endpoint upon every change to the workspace in which your app was installed.
+ - **Organization Details(Optional)**: Optionally include your contact email, privacy policy URL, terms of service URL, and any other relevant information. This helps Plane validate and approve your application should you choose to [list in the marketplace](#listing-your-app-on-plane-marketplace).
+
+4. If you're building an agent (with or without using Plane's ADK) capable of performing operations when assigned or mentioned, enable the **Is Mentionable** checkbox during app creation.
+5. Once the app is created, securely store the generated **Client ID** and **Client Secret**. You will need these credentials to interact with Plane's API during the OAuth flow and for making authenticated API requests.
+
+## Implement OAuth Flow
+
+### Generating Consent URL (Optional)
+
+This step is optional. This is needed only if the app should be installed from outside Plane's environment, the developer needs to generate the consent URL using the client ID generated during their app creation flow.
+
+If this flow needs to be triggered from Plane marketplace as well, then provide the URL in "Setup URL" field on application create screen to redirect the user from marketplace on clicking "Install App" button.
+
+Below are sample implementations:
+
+
+
+ ```python
+ import os
+ from urllib.parse import urlencode
+ params = {
+ "client_id": os.getenv("PLANE_CLIENT_ID"),
+ "response_type": "code",
+ "redirect_uri": os.getenv("PLANE_REDIRECT_URI"),
+ }
+ consent_url = f"https://api.plane.so/auth/o/authorize-app/?{urlencode(params)}"
+ ```
+
+
+ ```typescript
+ import { URLSearchParams } from 'url';
+ const params = new URLSearchParams({
+ client_id: process.env.PLANE_CLIENT_ID!,
+ response_type: "code",
+ redirect_uri: process.env.PLANE_REDIRECT_URI!,
+ });
+ const consentUrl = `https://api.plane.so/auth/o/authorize-app/?${params.toString()}`;
+ ```
+
+
+
+There are two types of authenticated actions your application can perform:
+
+1. **User-authorized actions**: Actions performed on behalf of a user after they grant permission to your app via OAuth.
+2. **App-authorized actions**: Actions that the app can perform independently within the workspace where it is installed (such as responding to webhooks or automation triggers).
+
+For both these flows, Plane will make a GET request to the Redirect URI with parameters as mentioned in the following sections.
+
+We will describe how to configure and use each type in the following sections.
+
+### App-Authorized Actions (Client Credentials Flow)
+
+When the app is installed, Plane will send an `app_installation_id` as part of the callback to the Redirect URI provided during consent URL generation. You can use this `app_installation_id` to request a bot token for your app.
+
+Plane will make a GET request to the Redirect URI with below parameters:
+
+| Parameter | Description |
+|-----------|-------------|
+| app_installation_id | The unique identifier for the app installation in the workspace |
+
+#### Examples
+
+
+
+ ```python
+ import base64
+ import requests
+ client_id = "your_client_id"
+ client_secret = "your_client_secret"
+ basic_auth = base64.b64encode(f"{client_id}:{client_secret}".encode()).decode()
+ payload = {
+ "grant_type": "client_credentials",
+ "app_installation_id": app_installation_id
+ }
+ response = requests.post(
+ url="https://api.plane.so/auth/o/token/",
+ headers={"Authorization": f"Basic {basic_auth}", "Content-Type": "application/x-www-form-urlencoded"},
+ data=payload
+ )
+ response_data = response.json()
+ bot_token = response_data['access_token']
+ expires_in = response_data["expires_in"]
+ ```
+
+
+ ```typescript
+ import axios from 'axios';
+ const clientId = "your_client_id";
+ const clientSecret = "your_client_secret";
+ const basicAuth = Buffer.from(`${clientId}:${clientSecret}`).toString('base64');
+ const payload = {
+ grant_type: "client_credentials",
+ app_installation_id: appInstallationId
+ };
+ const response = await axios.post(
+ "https://api.plane.so/auth/o/token/",
+ payload,
+ {
+ headers: {
+ Authorization: `Basic ${basicAuth}`,
+ "Content-Type": "application/x-www-form-urlencoded"
+ }
+ }
+ );
+ const responseData = response.data;
+ const botToken = responseData.access_token;
+ const expiresIn = responseData.expires_in;
+ ```
+
+
+
+### User-Authorized Actions (Authorization Code Flow)
+
+In this flow, your app exchanges the `code` received as a query parameter on the callback (to your Redirect URI) for an access token and refresh token. The access token is short-lived and must be refreshed using the refresh token when it expires. Both tokens should be securely stored.
+
+Plane will make a GET request to the Redirect URI with below parameters:
+
+| Parameter | Description | Required |
+|-----------|-------------|----------|
+| code | The authorization code that can be exchanged for an access token | Yes |
+| state | The state parameter that was passed in the authorization request | No |
+
+#### Examples
+
+
+
+ ```python
+ import requests
+ code = "authorization_code_from_callback"
+ client_id = "your_client_id"
+ client_secret = "your_client_secret"
+ redirect_uri = "your_redirect_uri"
+ payload = {
+ "grant_type": "authorization_code",
+ "code": code,
+ "client_id": client_id,
+ "client_secret": client_secret,
+ "redirect_uri": redirect_uri
+ }
+ response = requests.post(
+ url="https://api.plane.so/auth/o/token/",
+ headers={"Content-Type": "application/x-www-form-urlencoded"},
+ data=payload
+ )
+ response_data = response.json()
+ access_token = response_data["access_token"]
+ refresh_token = response_data["refresh_token"]
+ expires_in = response_data["expires_in"]
+ ```
+
+
+ ```typescript
+ import axios from 'axios';
+ const code = "authorization_code_from_callback";
+ const clientId = "your_client_id";
+ const clientSecret = "your_client_secret";
+const redirectUri = "your_redirect_uri";
+const payload = {
+ grant_type: "authorization_code",
+ code: code,
+ client_id: clientId,
+ client_secret: clientSecret,
+ redirect_uri: redirectUri
+};
+const response = await axios.post(
+ "https://api.plane.so/auth/o/token/",
+ payload,
+ {
+ headers: {
+ "Content-Type": "application/x-www-form-urlencoded"
+ }
+ }
+);
+const responseData = response.data;
+const accessToken = responseData.access_token;
+const refreshToken = responseData.refresh_token;
+const expiresIn = responseData.expires_in;
+```
+
+
+
+### Fetching App Installation Details
+
+In both user-authorized and app-authorized flows, the `app_installation_id` identifies the app's installation within a specific workspace. It is recommended that developers fetch workspace details after OAuth is successfully completed. Plane provides an `app-installation` endpoint that works with both types of tokens.
+
+#### Examples
+
+
+
+ ```python
+ import requests
+ headers = {"Authorization": f"Bearer {token}"}
+ response = requests.get(
+ url=f"https://api.plane.so/auth/o/app-installation/?id={app_installation_id}",
+ headers=headers
+ )
+ workspace_details = response.data[0]
+ ```
+
+
+ ```typescript
+ import axios from 'axios';
+ const headers = { Authorization: `Bearer ${token}` };
+ const response = await axios.get(
+ `https://api.plane.so/auth/o/app-installation/?id=${app_installation_id}`,
+ { headers }
+ );
+ const workspaceDetails = response.data[0];
+ ```
+
+
+
+#### Sample Response
+
+```json
+[
+ {
+ "id": "34b97361-8636-43dc-953e-90deedc8498f",
+ "workspace_detail": {
+ "name": "sandbox",
+ "slug": "sandbox",
+ "id": "7a2e5944-c117-4a7d-b5f4-058fe705d7d1",
+ "logo_url": null
+ },
+ "created_at": "2025-05-16T13:50:27.865821Z",
+ "updated_at": "2025-06-23T08:57:26.976742Z",
+ "deleted_at": null,
+ "status": "installed",
+ "workspace": "7a2e5944-c117-4a7d-b5f4-058fe705d7d1",
+ "application": "ab235529-388a-4f51-a55a-78272251f5f1",
+ "installed_by": "63333ab1-c605-42fc-82f7-5cd86799eca1",
+ "app_bot": "7286aaa7-9250-4851-a520-29c904fd7654",
+ "webhook": "b1f4b7f1-51e8-4919-a84c-0b1143b51d2c"
+ }
+]
+```
+
+## Obtain and store access tokens securely
+
+Once you have obtained the access token, you can use it to make authenticated API requests to Plane.
+Store the access token and refresh token securely in your database.
+
+
+## Make authenticated API requests to Plane
+
+For making authenticated API requests to Plane, you can use the access token obtained from the OAuth flow.
+
+API reference is available at [https://docs.plane.so/api-reference](https://docs.plane.so/api-reference).
+
+We have official SDKs for the following languages to simplify the OAuth flow and make it easier to call Plane's API.
+
+| Language | Package Link | Source Code |
+|----------|---------|-------------|
+| Node.js | [npm i @makeplane/plane-node-sdk](https://www.npmjs.com/package/@makeplane/plane-node-sdk) | [plane-node-sdk](https://github.com/makeplane/plane-node-sdk) |
+| Python | [pip install plane-sdk](https://pypi.org/project/plane-sdk/) | [plane-python-sdk](https://github.com/makeplane/plane-python-sdk) |
+
+## Handle Token Refresh
+
+When the access token expires, you can use the refresh token to get a new access token.
+
+#### Examples
+
+
+
+ ```python
+ refresh_payload = {
+ "grant_type": "refresh_token",
+ "refresh_token": refresh_token,
+ "client_id": client_id,
+ "client_secret": client_secret
+ }
+ refresh_response = requests.post(
+ url="https://api.plane.so/auth/o/token/",
+ headers={"Content-Type": "application/x-www-form-urlencoded"},
+ data=refresh_payload
+ )
+ refresh_response_data = refresh_response.json()
+ access_token = refresh_response_data["access_token"]
+ ```
+
+
+ ```typescript
+ const refreshPayload = {
+ grant_type: "refresh_token",
+ refresh_token: refreshToken,
+ client_id: clientId,
+ client_secret: clientSecret
+ };
+ const refreshResponse = await axios.post(
+ "https://api.plane.so/auth/o/token/",
+ refreshPayload,
+ {
+ headers: {
+ "Content-Type": "application/x-www-form-urlencoded"
+ }
+ }
+ );
+ const refreshResponseData = refreshResponse.data;
+ const accessToken = refreshResponseData.access_token;
+ ```
+
+
+
+## Listing Your App on Plane Marketplace
+
+Apps built using the OAuth flow can be listed on the Plane Marketplace: [https://plane.so/marketplace/integrations](https://plane.so/marketplace/integrations)
+
+To list your app, please contact the Plane team at [**support@plane.so**](mailto:support@plane.so).
\ No newline at end of file
diff --git a/docs/apps/overview.mdx b/docs/apps/overview.mdx
index 96bea1d..de9bc54 100644
--- a/docs/apps/overview.mdx
+++ b/docs/apps/overview.mdx
@@ -43,4 +43,4 @@ integrations that fit your specific workflow.
## Get Started
-Next, follow our [quickstart guide](/apps/quickstart) to build your first Plane App.
+Next, follow our [quickstart guide](/apps/build-plane-app) to build your first Plane App.
diff --git a/docs/apps/quickstart.mdx b/docs/apps/quickstart.mdx
deleted file mode 100644
index 552a186..0000000
--- a/docs/apps/quickstart.mdx
+++ /dev/null
@@ -1,338 +0,0 @@
----
-title: Build a Plane App
-sidebar_label: Quickstart
-description: Step-by-step development guide to building a Plane App
----
-
-import Tabs from "@theme/Tabs";
-import TabItem from "@theme/TabItem";
-
-{frontMatter.description && (
-
-
{frontMatter.description}
-)}
-
-:::tip Beta
-Plane Apps are currently in **Beta**. Some aspects of the API may change. Please send
-feedback to support@plane.so.
-:::
-
-## Prerequisites
-
-- A [Plane](https://app.plane.so) workspace
-- Admin access to your Plane workspace settings
-- Familiarity with OAuth 2.0 concepts
-- A backend server to handle OAuth token exchange
-
-## High-Level Workflow
-
-1. Register your Plane App
-2. Implement OAuth
-3. Obtain access tokens
-4. Make authenticated API requests to Plane
-5. Handle token refresh
-
-## Register Your Plane App
-
-1. Go to `https://app.plane.so//settings/applications/`.
-2. Click **Build your own**.
-3. Fill out the required details:
- - **Name** and **Short Description**
- - **Redirect URIs**
- - **Contact Details**
- - **Setup URL (Optional)**
- - **Webhook URL Endpoint (Optional)**
- - **Organization Details (Optional)**
-4. If you're building an agent, enable the **Is Mentionable** checkbox.
-5. Once the app is created, securely store the generated **Client ID** and **Client Secret**.
-
-## Implement OAuth Flow
-
-### Generating Consent URL (Optional)
-
-If your app should be installed from outside Plane, generate the consent URL using the
-client ID from app creation. Provide this URL in the "Setup URL" field if you want the
-flow triggered from the marketplace.
-
-
-
- ```python
- import os
- from urllib.parse import urlencode
- params = {
- "client_id": os.getenv("PLANE_CLIENT_ID"),
- "response_type": "code",
- "redirect_uri": os.getenv("PLANE_REDIRECT_URI"),
- }
- consent_url = f"https://api.plane.so/auth/o/authorize-app/?{urlencode(params)}"
- ```
-
-
- ```typescript
- import { URLSearchParams } from 'url';
- const params = new URLSearchParams({
- client_id: process.env.PLANE_CLIENT_ID!,
- response_type: "code",
- redirect_uri: process.env.PLANE_REDIRECT_URI!,
- });
- const consentUrl = `https://api.plane.so/auth/o/authorize-app/?${params.toString()}`;
- ```
-
-
-
-There are two types of authenticated actions your app can perform:
-
-1. **User-authorized actions**: Actions performed on behalf of a user after they grant permission via OAuth.
-2. **App-authorized actions**: Actions the app can perform independently within the workspace where it is installed.
-
-For both flows, Plane will make a GET request to the Redirect URI with parameters as
-described below.
-
-### App-Authorized Actions (Client Credentials Flow)
-
-When the app is installed, Plane will send an `app_installation_id` as part of the
-callback. Use this to request a bot token for your app.
-
-| Parameter | Description |
-| ------------------- | --------------------------------------------------------------- |
-| app_installation_id | The unique identifier for the app installation in the workspace |
-
-#### Example
-
-
-
- ```python
- import base64
- import requests
- client_id = "your_client_id"
- client_secret = "your_client_secret"
- basic_auth = base64.b64encode(f"{client_id}:{client_secret}".encode()).decode()
- payload = {
- "grant_type": "client_credentials",
- "app_installation_id": app_installation_id
- }
- response = requests.post(
- url="https://api.plane.so/auth/o/token/",
- headers={"Authorization": f"Basic {basic_auth}", "Content-Type": "application/x-www-form-urlencoded"},
- data=payload
- )
- response_data = response.json()
- bot_token = response_data['access_token']
- expires_in = response_data["expires_in"]
- ```
-
-
-```typescript
-import axios from 'axios';
-const clientId = "your_client_id";
-const clientSecret = "your_client_secret";
-const basicAuth = Buffer.from(`${clientId}:${clientSecret}`).toString('base64');
-const payload = {
- grant_type: "client_credentials",
- app_installation_id: appInstallationId
-};
-const response = await axios.post(
- "https://api.plane.so/auth/o/token/",
- payload,
- {
- headers: {
- Authorization: `Basic ${basicAuth}`,
- "Content-Type": "application/x-www-form-urlencoded"
- }
- }
-);
-const responseData = response.data;
-const botToken = responseData.access_token;
-const expiresIn = responseData.expires_in;
-```
-
-
-
-### User-Authorized Actions (Authorization Code Flow)
-
-In this flow, your app exchanges the `code` received as a query parameter on the
-callback for an access token and refresh token. The access token is short-lived and
-must be refreshed using the refresh token when it expires. Store both tokens securely.
-
-Plane will make a GET request to the Redirect URI with:
-
-| Parameter | Description | Required |
-| --------- | ------------------------------------------------------- | -------- |
-| code | The authorization code to exchange for an access token | Yes |
-| state | The state parameter passed in the authorization request | No |
-
-#### Example
-
-
-
- ```python
- import requests
- code = "authorization_code_from_callback"
- client_id = "your_client_id"
- client_secret = "your_client_secret"
- redirect_uri = "your_redirect_uri"
- payload = {
- "grant_type": "authorization_code",
- "code": code,
- "client_id": client_id,
- "client_secret": client_secret,
- "redirect_uri": redirect_uri
- }
- response = requests.post(
- url="https://api.plane.so/auth/o/token/",
- headers={"Content-Type": "application/x-www-form-urlencoded"},
- data=payload
- )
- response_data = response.json()
- access_token = response_data["access_token"]
- refresh_token = response_data["refresh_token"]
- expires_in = response_data["expires_in"]
- ```
-
-
- ```typescript
- import axios from 'axios';
- const code = "authorization_code_from_callback";
- const clientId = "your_client_id";
- const clientSecret = "your_client_secret";
-const redirectUri = "your_redirect_uri";
-const payload = {
- grant_type: "authorization_code",
- code: code,
- client_id: clientId,
- client_secret: clientSecret,
- redirect_uri: redirectUri
-};
-const response = await axios.post(
- "https://api.plane.so/auth/o/token/",
- payload,
- {
- headers: {
- "Content-Type": "application/x-www-form-urlencoded"
- }
- }
-);
-const responseData = response.data;
-const accessToken = responseData.access_token;
-const refreshToken = responseData.refresh_token;
-const expiresIn = responseData.expires_in;
-```
-
-
-
-### Fetching App Installation Details
-
-In both flows, the `app_installation_id` identifies the app's installation within a
-workspace. Fetch workspace details after OAuth is completed. Use the
-`app-installation` endpoint with either type of token.
-
-
-
- ```python
- import requests
- headers = {"Authorization": f"Bearer {token}"}
- response = requests.get(
- url=f"https://api.plane.so/auth/o/app-installation/?id={app_installation_id}",
- headers=headers
- )
- workspace_details = response.data[0]
- ```
-
-
- ```typescript
- import axios from 'axios';
- const headers = { Authorization: `Bearer ${token}` };
- const response = await axios.get(
- `https://api.plane.so/auth/o/app-installation/?id=${app_installation_id}`,
- { headers }
- );
- const workspaceDetails = response.data[0];
- ```
-
-
-
-#### Sample Response
-
-```json
-[
- {
- "id": "34b97361-8636-43dc-953e-90deedc8498f",
- "workspace_detail": {
- "name": "sandbox",
- "slug": "sandbox",
- "id": "7a2e5944-c117-4a7d-b5f4-058fe705d7d1",
- "logo_url": null
- },
- "created_at": "2025-05-16T13:50:27.865821Z",
- "updated_at": "2025-06-23T08:57:26.976742Z",
- "deleted_at": null,
- "status": "installed",
- "workspace": "7a2e5944-c117-4a7d-b5f4-058fe705d7d1",
- "application": "ab235529-388a-4f51-a55a-78272251f5f1",
- "installed_by": "63333ab1-c605-42fc-82f7-5cd86799eca1",
- "app_bot": "7286aaa7-9250-4851-a520-29c904fd7654",
- "webhook": "b1f4b7f1-51e8-4919-a84c-0b1143b51d2c"
- }
-]
-```
-
-## Obtain and store access tokens securely
-
-Store the access and refresh tokens securely in your database or secrets manager.
-
-## Make authenticated API requests to Plane
-
-Use the access token to make authenticated requests to Plane via the
-[Plane API](/api/introduction) or [official SDKs](/sdks/overview).
-
-## Handle Token Refresh
-
-When the access token expires, use the refresh token to obtain a new access token.
-
-
-
- ```python
- refresh_payload = {
- "grant_type": "refresh_token",
- "refresh_token": refresh_token,
- "client_id": client_id,
- "client_secret": client_secret
- }
- refresh_response = requests.post(
- url="https://api.plane.so/auth/o/token/",
- headers={"Content-Type": "application/x-www-form-urlencoded"},
- data=refresh_payload
- )
- refresh_response_data = refresh_response.json()
- access_token = refresh_response_data["access_token"]
- ```
-
-
- ```typescript
- const refreshPayload = {
- grant_type: "refresh_token",
- refresh_token: refreshToken,
- client_id: clientId,
- client_secret: clientSecret
- };
- const refreshResponse = await axios.post(
- "https://api.plane.so/auth/o/token/",
- refreshPayload,
- {
- headers: {
- "Content-Type": "application/x-www-form-urlencoded"
- }
- }
- );
- const refreshResponseData = refreshResponse.data;
- const accessToken = refreshResponseData.access_token;
- ```
-
-
-
-## Listing Your App on Plane Marketplace
-
-Apps built using the OAuth flow can be listed on the Plane Marketplace:
-[https://plane.so/marketplace/integrations](https://plane.so/marketplace/integrations)
-
-To list your app, contact the Plane team at [support@plane.so](mailto:support@plane.so).
diff --git a/docs/intro.md b/docs/intro.md
index 80059d1..30334cb 100644
--- a/docs/intro.md
+++ b/docs/intro.md
@@ -2,36 +2,37 @@
title: Introduction
slug: /
sidebar_position: 1
-description: Explore our guides and examples to integrate Plane
+description: Complete developer documentation for Plane - self-hosting guides, REST API reference, webhooks, authentication, and tools for building custom integrations and applications.
---
-# Plane Developer Documentation
+# Self-host, integrate, and extend Plane
-{frontMatter.description &&
{frontMatter.description}
}
+Welcome to Plane's developer documentation. Here you'll find everything you need to deploy, customize, integrate, and extend Plane's capabilities for your organization.
-:::tip Let's Go!
-Get Started with Self-Hosting right away by visiting our [QuickStart](/self-hosting/overview).
-:::
-
-Greetings developer! 👋
-
-We're happy you're here. This site is focused on making it easy for you to
-integrate with Plane. Whether hosting Plane yourself or creating a custom
-integration, this is where you'll find all the fun details you need. 🦾
+## What's in here
import { Card } from '@site/src/components/Card';
import { CardGroup } from '@site/src/components/CardGroup';
-## Solutions
-
-
- Learn how to self-host Plane.
+
+ Deploy Plane on your own infrastructure with full control over your data.
-
- Use our API reference to build a custom integration.
+
+ Complete documentation of our REST API.
-
- Learn how to integrate Plane's webhooks with your service.
+
+ Set up real-time notifications so your other systems know when stuff happens in Plane.
+
+## Where to start
+Not sure where to begin? Here's what we'd suggest:
+
+If you're setting up Plane for the first time, start with the self-hosting section. We'll get you up and running.
+
+If you're connecting Plane to something else, jump to the API reference. Get familiar with how our data is structured and try a few calls.
+
+## When you get stuck
+Things break, documentation isn't perfect, and sometimes you just need to talk to a human.
+Reach out on Discord - our community is pretty helpful and we're usually around to answer questions.
\ No newline at end of file
diff --git a/docs/ai-solutions/overview.mdx b/docs/mcp-server/overview.mdx
similarity index 97%
rename from docs/ai-solutions/overview.mdx
rename to docs/mcp-server/overview.mdx
index a3b62f4..91548b4 100644
--- a/docs/ai-solutions/overview.mdx
+++ b/docs/mcp-server/overview.mdx
@@ -1,6 +1,6 @@
---
-title: AI Solutions Overview
-sidebar_label: Overview
+title: MCP Server
+sidebar_label: MCP Server
description: Use the Plane MCP server to integrate with Plane
sidebar_position: 1
---
diff --git a/docs/sdks/overview.mdx b/docs/sdks/overview.mdx
index bdeaab3..8460839 100644
--- a/docs/sdks/overview.mdx
+++ b/docs/sdks/overview.mdx
@@ -1,6 +1,6 @@
---
-title: SDKs Overview
-sidebar_label: Overview
+title: SDKs
+sidebar_label: SDKs
description: Use Plane SDKs to integrate with Plane
sidebar_position: 1
---
diff --git a/docs/self-hosting/_category_.yml b/docs/self-hosting/_category_.yml
index 5a0d840..1e090f8 100644
--- a/docs/self-hosting/_category_.yml
+++ b/docs/self-hosting/_category_.yml
@@ -1,2 +1,3 @@
label: "Self-Hosting"
position: 2
+collapsed: false
diff --git a/docs/self-hosting/editions-and-versions.mdx b/docs/self-hosting/editions-and-versions.mdx
index 7a4798f..3b700ce 100644
--- a/docs/self-hosting/editions-and-versions.mdx
+++ b/docs/self-hosting/editions-and-versions.mdx
@@ -1,6 +1,6 @@
---
title: Understanding Plane's Editions
-sidebar_label: Plane Editions
+sidebar_label: About Editions
sidebar_position: 2
---
@@ -9,12 +9,9 @@ sidebar_position: 2
{frontMatter.description}
)}
-Plane is available in three editions, based on how it is deployed. As of 2025, our
-Cloud is the only hosted edition. We also offer two unique self-hosted editions
-tailored to different needs: the open-source Community Edition and the recommended
-Commercial Edition.
+Plane comes in three editions by how its deployed. Our Cloud is our only hosted edition as of 2025. Additionally, we offer two unique self-hosted editions tailored to meet two sets of unique needs—the open-source Community Edition and the recommended Commercial Edition.
-## About Our Self-Hosted Editions
+## About our self-hosted editions
### Community Edition
@@ -24,19 +21,14 @@ Built with transparency in mind, the Community Edition:
- Allows contributions to the repo through modifications and customizations
- Has no code dependencies or restrictions on or from the Commercial Edition
-It’s ideal for those who want to try Plane first, audit the code for security, and see
-how each service works with the others. Tens of thousands of users have used it, and
-many have contributed to it.
+It’s ideal for those who want to try Plane first, audit the code for security, and see how each one of services works with the others. Several tens of thousands of uses have used it and a significant number have contributed to it.
-The Community Edition matches the Free tier of the Cloud edition in feature
-availability. To upgrade to paid plans, you must first switch to the Commercial
-Edition.
+The Community Edition is at par with the Free tier of the Cloud edition in its feature availability. To upgrade to paid plans, you must first switch to the Commercial Edition.
+​
### Commercial Edition
-Designed for teams that need governance, compliance, and privacy controls, the
-Commercial Edition is ideal for organizations looking to unlock advanced work
-management and security features.
+Designed for teams that want governance, compliance, and privacy controls, the Commercial Edition is ideal for teams that want to try Plane with an intent to unlock advanced work management and security features.
This edition also comes with a Free tier and allows seamless upgrades to all paid
plans. It offers:
@@ -45,19 +37,19 @@ plans. It offers:
- A bundle of 12 free user seats per workspace, so there are no surprises when you upgrade
- An intuitive upgrade flow that automatically calculates the number of seats you need based on the number of users with paid roles in your workspace, so you never have to guess
-## Why We Separate Editions
+## Why we separate editions
We’ve designed Plane’s editions to serve diverse user needs while staying true to the
ethos of open source.
-- The **Community Edition** is completely open-source, with no restrictions beyond those outlined in the [AGPL v3.0 license](https://github.com/makeplane/plane/blob/preview/LICENSE.txt). This edition is now ranked #1 in our space on GitHub.
+- The **Community Edition** is completely open-source, with no restrictions beyond those outlined in the [AGPL v3.0 license](https://github.com/makeplane/plane/blob/preview/LICENSE.txt). This is the edition that is now ranking at #1 in our space on GitHub.
- The **Commercial Edition** remains closed-source to offer enterprise-grade features and seamless scalability for businesses.
Unlike some open-core companies, we’ve adopted a clean separation to keep things
simple and transparent. There’s no hidden code that limits modifications on the
Community Edition, and no forced migrations from one edition to another.
-## Differences in Versions Between Editions
+## Differences in versions between Editions
Each of our editions is built on a distinct codebase. Versions differ based on how we
ship new code according to our three separate release cycles. This distinction allows
diff --git a/docs/self-hosting/govern/_category_.yml b/docs/self-hosting/govern/_category_.yml
index 2df6327..2322fb7 100644
--- a/docs/self-hosting/govern/_category_.yml
+++ b/docs/self-hosting/govern/_category_.yml
@@ -1 +1,2 @@
label: "Configure"
+collapsed: false
\ No newline at end of file
diff --git a/docs/self-hosting/govern/integrations/github.mdx b/docs/self-hosting/govern/integrations/github.mdx
index 23fe203..03185d8 100644
--- a/docs/self-hosting/govern/integrations/github.mdx
+++ b/docs/self-hosting/govern/integrations/github.mdx
@@ -3,124 +3,253 @@ title: Configure GitHub App for Plane integration
sidebar_label: GitHub
---
-import Tabs from "@theme/Tabs";
-import TabItem from "@theme/TabItem";
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
-{frontMatter.description && (
+{frontMatter.description &&