review fixes

Author: danciaclara

docs/.vitepress/config.mts

@@ -652,15 +652,12 @@ export default withMermaid(defineConfig({
             {
               text: 'Build Plane App', collapsed: false, items: [
                 { text: 'Overview', link: '/dev-tools/build-plane-app/overview' },
-                { text: 'Create an OAuth Application', link: '/dev-tools/build-plane-app/create-oauth-application' },
-                { text: 'Choose Your Flow', link: '/dev-tools/build-plane-app/choose-token-flow' },
-                { text: 'Making API Requests', link: '/dev-tools/build-plane-app/making-api-requests' },
-                { text: 'Handling Webhooks', link: '/dev-tools/build-plane-app/webhooks' },
-                { text: 'Local Development', link: '/dev-tools/build-plane-app/local-development' },
-                { text: 'OAuth Scopes', link: '/dev-tools/build-plane-app/oauth-scopes' },
+                { text: 'Create an OAuth application', link: '/dev-tools/build-plane-app/create-oauth-application' },
+                { text: 'Choose token Flow', link: '/dev-tools/build-plane-app/choose-token-flow' },
+                { text: 'Handling webhooks', link: '/dev-tools/build-plane-app/webhooks' },
+                { text: 'OAuth scopes', link: '/dev-tools/build-plane-app/oauth-scopes' },
                 { text: 'SDKs', link: '/dev-tools/build-plane-app/sdks' },
-                { text: 'Complete Examples', link: '/dev-tools/build-plane-app/examples' },
-                { text: 'Next Steps', link: '/dev-tools/build-plane-app/next-steps' }
+                { text: 'Complete examples', link: '/dev-tools/build-plane-app/examples' }
               ]
             },
             {

docs/dev-tools/build-plane-app/choose-token-flow.md

@@ -1,9 +1,9 @@
 ---
-title: Choose Your Flow
+title: Choose token flow
 description: Decide between Bot Token and User Token flows and learn how to implement them.
 ---
 
-# Choose Your Flow
+# Choose token flow
 
 Plane supports two OAuth flows:
 
@@ -18,7 +18,7 @@ Most integrations should use the **Bot Token flow**. Use User Token only when yo
 
 ---
 
-## Bot Token Flow
+## Bot token flow
 
 Use this flow for agents, webhook handlers, and automation that acts autonomously.
 
@@ -38,7 +38,7 @@ sequenceDiagram
     YourApp->>YourApp: Store credentials
 ```
 
-### 1. Redirect to Authorization
+### 1. Redirect to authorization
 
 When a user clicks "Install", redirect them to Plane's consent screen:
 
@@ -49,7 +49,7 @@ GET https://api.plane.so/auth/o/authorize-app/
   &redirect_uri=https://your-app.com/callback
 ```
 
-### 2. Handle the Callback
+### 2. Handle the callback
 
 After the user approves, Plane redirects to your Redirect URI with:
 
@@ -58,7 +58,7 @@ After the user approves, Plane redirects to your Redirect URI with:
 | `app_installation_id` | Unique identifier for this installation   |
 | `code`                | Authorization code (not used in bot flow) |
 
-### 3. Exchange for Bot Token
+### 3. Exchange for bot token
 
 ```
 POST https://api.plane.so/auth/o/token/
@@ -81,7 +81,7 @@ grant_type=client_credentials
 }
 ```
 
-### 4. Get Workspace Details
+### 4. Get workspace details
 
 ```
 GET https://api.plane.so/auth/o/app-installation/?id=APP_INSTALLATION_ID
@@ -107,7 +107,7 @@ Authorization: Bearer YOUR_BOT_TOKEN
 
 Store the `workspace_detail.slug` for API calls and `app_installation_id` for token refresh.
 
-### 5. Refresh Bot Token
+### 5. Refresh bot token
 
 Bot tokens expire. Request a new one using the stored `app_installation_id`:
 
@@ -123,7 +123,7 @@ grant_type=client_credentials
 
 ---
 
-## User Token Flow
+## User token flow
 
 Use this flow when your app needs to act on behalf of a specific user.
 
@@ -143,7 +143,7 @@ sequenceDiagram
     YourApp->>YourApp: Store tokens for user
 ```
 
-### 1. Redirect to Authorization
+### 1. Redirect to authorization
 
 ```
 GET https://api.plane.so/auth/o/authorize-app/
@@ -158,7 +158,7 @@ GET https://api.plane.so/auth/o/authorize-app/
 Include a random `state` parameter to prevent CSRF attacks. Verify it matches when handling the callback.
 :::
 
-### 2. Handle the Callback
+### 2. Handle the callback
 
 After approval, Plane redirects to your Redirect URI with:
 
@@ -167,7 +167,7 @@ After approval, Plane redirects to your Redirect URI with:
 | `code`    | Authorization code to exchange for tokens  |
 | `state`   | Your state parameter (verify this matches) |
 
-### 3. Exchange Code for Tokens
+### 3. Exchange code for tokens
 
 ```
 POST https://api.plane.so/auth/o/token/
@@ -192,7 +192,7 @@ grant_type=authorization_code
 }
 ```
 
-### 4. Refresh User Token
+### 4. Refresh user token
 
 ```
 POST https://api.plane.so/auth/o/token/
@@ -203,3 +203,16 @@ grant_type=refresh_token
 &client_id=YOUR_CLIENT_ID
 &client_secret=YOUR_CLIENT_SECRET
 ```
+
+---
+
+## Making API requests
+
+Include the token in the `Authorization` header:
+
+```
+GET https://api.plane.so/api/v1/workspaces/{workspace_slug}/projects/
+Authorization: Bearer YOUR_TOKEN
+```
+
+See the [API Reference](/api-reference/introduction) for available endpoints.

docs/dev-tools/build-plane-app/create-oauth-application.md

@@ -5,8 +5,8 @@ description: Register your app to get Client ID and Secret.
 
 # Create an OAuth Application
 
-1. Navigate to **Workspace Settings** → **Integrations** (`https://app.plane.so/<workspace>/settings/integrations/`)
-2. Click **Build your own**
+1. Navigate to **Workspace Settings** → **Integrations**. `https://app.plane.so/<workspace>/settings/integrations/`
+2. Click **Build your own**.
 3. Fill in the required details:
 
 | Field            | Description                                                                                            |
@@ -16,8 +16,8 @@ description: Register your app to get Client ID and Secret.
 | **Redirect URI** | Callback URL where Plane sends users after they approve access, along with the authorization code.     |
 | **Webhook URL**  | Endpoint for receiving event notifications                                                             |
 
-4. For agents that respond to @mentions, enable **"Enable App Mentions"**
-5. Save and store your **Client ID** and **Client Secret** securely
+4. For agents that respond to @mentions, enable **"Enable App Mentions"**.
+5. Save and store your **Client ID** and **Client Secret** securely.
 6. Select the scopes you need for your app from the **Scopes & Permissions** section. See [OAuth Scopes](/dev-tools/build-plane-app/oauth-scopes) for more information on the available scopes.
 
 ::: warning

docs/dev-tools/build-plane-app/examples.md

@@ -1,13 +1,13 @@
 ---
-title: Complete Examples
+title: Complete examples
 description: Full code examples for Node.js (Express) and Python (Flask).
 ---
 
-# Complete Examples
+# Complete examples
 
-::: details TypeScript (Express) - Full Implementation
+::: code-group
 
-```typescript
+```typescript [TypeScript (Express)]
 import express from "express";
 import axios from "axios";
 import crypto from "crypto";
@@ -114,11 +114,7 @@ app.post("/webhook", express.raw({ type: "application/json" }), (req, res) => {
 app.listen(3000, () => console.log("Server running on http://localhost:3000"));
 ```
 
-:::
-
-::: details Python (Flask) - Full Implementation
-
-```python
+```python [Python (Flask)]
 import os
 import hmac
 import hashlib
@@ -235,3 +231,14 @@ if __name__ == "__main__":
 ```
 
 :::
+
+## Next Steps
+
+- [Build an Agent](/dev-tools/agents/overview) - Create AI agents that respond to @mentions
+- [API Reference](/api-reference/introduction) - Explore the full Plane API
+- [Webhook Events](/dev-tools/intro-webhooks) - All webhook event types
+- [Example: PRD Agent](https://github.com/makeplane/prd-agent) - Complete agent implementation
+
+## Publish to Marketplace
+
+Apps can be listed on the [Plane Marketplace](https://plane.so/marketplace/integrations). Contact [support@plane.so](mailto:support@plane.so) to list your app.

docs/dev-tools/build-plane-app/local-development.md

@@ -1,4 +1,9 @@
-# OAuth Scopes
+---
+title: OAuth Scopes
+description: All OAuth scopes available when building a Plane app.
+---
+
+# OAuth scopes
 
 This document lists all OAuth scopes available when building a Plane app. Request only the scopes your app needs.