Add screenshot placeholders and restructure token setup documentation

code-reviews/faq.md

@@ -61,7 +61,21 @@ kluster.ai sources vulnerability data from public CVE databases that are continu
 
 ### How can I provide feedback about issues detected by kluster.ai?
 
-Each time a code review is done, a feedback option is available from the extension or in the platform. Your feedback helps improve detection accuracy and reduce false positives.
+You can provide feedback on code review results from your IDE or from the kluster.ai platform.
+
+**From your IDE**
+
+In the kluster.ai extension sidebar, open **Recent Reviews** to see your latest review results. Click on a review to open its details, then use the thumbs up or thumbs down buttons on any issue to rate the finding.
+
+![kluster.ai review details in IDE with feedback buttons on an issue](/images/code-reviews/faq/faq-feedback-01.webp)
+
+**From the kluster.ai platform**
+
+Open [Review History](https://platform.kluster.ai/dashboards/logs){target=\_blank} in the kluster.ai platform to see all past code reviews. Click on any review to open its details. In the **Your Feedback** section, select **Yes** (thumbs up) or **No** (thumbs down) to rate the review, and optionally add comments before clicking **Submit Feedback**.
+
+![kluster.ai platform review detail page with Your Feedback section](/images/code-reviews/faq/faq-feedback-02.webp)
+
+Your feedback helps improve detection accuracy and reduce false positives across future reviews.
 
 ### What should I do if kluster.ai flags a false positive?
 

code-reviews/pr-reviews/bitbucket.md

@@ -32,33 +32,48 @@ The kluster.ai bot requires a Bitbucket API token to access your repositories an
 !!! tip "Use a dedicated service account"
     Reviews posted by the bot are attributed to the API token owner. To avoid reviews appearing under a personal account, create a dedicated Atlassian account for kluster and generate the API token from that account.
 
+Bitbucket offers two methods for creating API tokens: **Create API token** and **Create API token with scopes**. Select **Create API token** to follow the recommended setup below; it grants all required permissions by default.
+
 1. Sign in to the Atlassian account that will be associated with the kluster.ai bot reviews.
-2. Open the [API tokens](https://id.atlassian.com/manage-profile/security/api-tokens){target=\_blank} page in your Atlassian account settings.
-3. Click **Create token**. Enter a descriptive label (for example, "kluster.ai PR Reviews") and choose an expiration date that aligns with your security policy.
-4. When prompted to choose a product, select **Bitbucket**.
-5. Grant the token the scopes listed in the following table. All scopes are required for the bot to analyze code, post review comments, and manage webhooks:
-
-    |    Category    |                    Scope                     |                 Description                 |
-    |:--------------:|:--------------------------------------------:|:-------------------------------------------:|
-    | Account & User |        <pre>```read:account```</pre>         |            View users' profiles.            |
-    | Account & User |     <pre>```read:user:bitbucket```</pre>     |               View user info.               |
-    |   Repository   |  <pre>```read:repository:bitbucket```</pre>  |           View your repositories.           |
-    |   Repository   | <pre>```write:repository:bitbucket```</pre>  |          Modify your repositories.          |
-    | Pull Requests  | <pre>```read:pullrequest:bitbucket```</pre>  |          View your pull requests.           |
-    | Pull Requests  | <pre>```write:pullrequest:bitbucket```</pre> |         Modify your pull requests.          |
-    |     Issues     |    <pre>```read:issue:bitbucket```</pre>     |              View your issues.              |
-    |     Issues     |    <pre>```write:issue:bitbucket```</pre>    |             Modify your issues.             |
-    |   Workspace    |  <pre>```read:workspace:bitbucket```</pre>   |            View your workspaces.            |
-    |   Workspace    |   <pre>```admin:project:bitbucket```</pre>   |          Administer your projects.          |
-    |    Webhooks    |   <pre>```read:webhook:bitbucket```</pre>    |             View your webhooks.             |
-    |    Webhooks    |   <pre>```write:webhook:bitbucket```</pre>   |            Modify your webhooks.            |
-    |   Pipelines    |   <pre>```read:pipeline:bitbucket```</pre>   |            View your pipelines.             |
-    |   Pipelines    |    <pre>```read:runner:bitbucket```</pre>    | View your workspaces/repositories' runners. |
-
-    !!! tip "Copy scopes to find them quickly"
-        Click the copy button next to each scope in the table and paste it into the search field on the Bitbucket token creation page to locate the permission.
-
-6. Click **Create**, then copy the token immediately. The token value is only displayed once and cannot be retrieved later.
+2. Open the [API tokens](https://id.atlassian.com/manage-profile/security/api-tokens){target=\_blank} page in your Atlassian account settings and click **Create API token**.
+3. Enter a descriptive name (for example, "kluster.ai PR Reviews"), choose an expiration date that aligns with your security policy, and click **Create**.
+
+    ![Create an API token dialog with name, expiration, and Create button](/images/code-reviews/pr-reviews/pr-reviews-bitbucket-05.webp)
+
+4. Copy the token immediately. The token value is only displayed once and cannot be retrieved later.
+
+??? note "Alternative: Create API token with scopes"
+    If you want granular control over which permissions the token has, select **Create API token with scopes** instead. This method uses a multi-step wizard where you choose the app, then select individual scopes.
+
+    1. On the [API tokens](https://id.atlassian.com/manage-profile/security/api-tokens){target=\_blank} page, click **Create API token with scopes**.
+    2. Enter a descriptive name and set an expiration date, then click **Next**.
+    3. Under **Select the app**, choose **Bitbucket**, then click **Next**.
+    4. Enable the scopes listed in the following table. All scopes are required for the bot to analyze code, post review comments, and manage webhooks:
+
+        |    Category    |                    Scope                     |                 Description                 |
+        |:--------------:|:--------------------------------------------:|:-------------------------------------------:|
+        | Account & User |        <pre>```read:account```</pre>         |            View users' profiles.            |
+        | Account & User |     <pre>```read:user:bitbucket```</pre>     |               View user info.               |
+        |   Repository   |  <pre>```read:repository:bitbucket```</pre>  |           View your repositories.           |
+        |   Repository   | <pre>```write:repository:bitbucket```</pre>  |          Modify your repositories.          |
+        | Pull Requests  | <pre>```read:pullrequest:bitbucket```</pre>  |          View your pull requests.           |
+        | Pull Requests  | <pre>```write:pullrequest:bitbucket```</pre> |         Modify your pull requests.          |
+        |     Issues     |    <pre>```read:issue:bitbucket```</pre>     |              View your issues.              |
+        |     Issues     |    <pre>```write:issue:bitbucket```</pre>    |             Modify your issues.             |
+        |   Workspace    |  <pre>```read:workspace:bitbucket```</pre>   |            View your workspaces.            |
+        |   Workspace    |   <pre>```admin:project:bitbucket```</pre>   |          Administer your projects.          |
+        |    Webhooks    |   <pre>```read:webhook:bitbucket```</pre>    |             View your webhooks.             |
+        |    Webhooks    |   <pre>```write:webhook:bitbucket```</pre>   |            Modify your webhooks.            |
+        |   Pipelines    |   <pre>```read:pipeline:bitbucket```</pre>   |            View your pipelines.             |
+        |   Pipelines    |    <pre>```read:runner:bitbucket```</pre>    | View your workspaces/repositories' runners. |
+
+        !!! tip "Copy scopes to find them quickly"
+            Click the copy button next to each scope in the table and paste it into the search field on the Bitbucket token creation page to locate the permission.
+
+    5. Click **Next**, then copy the token immediately. The token value is only displayed once and cannot be retrieved later.
+
+    !!! tip
+        The standard API token is recommended for most users because it includes all required permissions by default. Use a scoped token only if limiting specific permissions is a priority for your organization.
 
 ## Connect Bitbucket
 

code-reviews/pr-reviews/gitlab.md

@@ -20,14 +20,14 @@ Before getting started, ensure you have:
 
 - A [kluster.ai](https://platform.kluster.ai/signup){target=\_blank} account.
 - A GitLab account with at least **Developer** access to the projects you want to review.
-- A GitLab personal access token with the `api` scope. See [Create an access token](#create-an-access-token) for instructions.
+- A GitLab personal access token with the `api`, `read_api`, and `read_user` scopes. See [Create an access token](#create-an-access-token) for instructions.
 
 !!! warning "Verify account permissions"
     The account that generates the access token must have at least **Developer** role in the target project or group. Having the correct token scopes (such as `api`) is not enough. The account itself needs Developer-level permissions. If the account only has Guest access, webhook installation will fail silently and PR reviews will not appear. After fixing the account's role, click **Re-install** on the PR Reviews page in the kluster.ai platform to complete the setup.
 
 ## Create an access token
 
-The kluster.ai bot requires a GitLab personal access token with the `api` scope to read merge requests and post review comments.
+The kluster.ai bot requires a GitLab personal access token with the `api`, `read_api`, and `read_user` scopes to read merge requests and post review comments.
 
 !!! warning "Project access tokens are not supported"
     kluster requires a **Personal access token**. Do not use a **Project access token**. These look similar in the GitLab UI but do not provide the permissions kluster needs to install webhooks across your projects. If you previously configured kluster with a project access token and reviews are not appearing, generate a new personal access token, then click **Re-install** on the PR Reviews page in the kluster.ai platform.
@@ -38,17 +38,23 @@ The kluster.ai bot requires a GitLab personal access token with the `api` scope
 The kluster.ai bot uses a **Legacy** personal access token. GitLab now shows two options when you create a token: **Legacy token** and **Fine-grained token (Beta)**. Select **Legacy token** to follow the recommended setup below; it includes all the permissions kluster needs by default.
 
 1. Sign in to the GitLab account that will be associated with the kluster.ai bot reviews.
-2. Open the [Personal access tokens](https://gitlab.com/-/user_settings/personal_access_tokens){target=\_blank} page and click **Add new token**.
+2. Open the [Personal access tokens](https://gitlab.com/-/user_settings/personal_access_tokens){target=\_blank} page and click **Generate token**.
 3. When prompted to choose a token type, select **Legacy token**.
+
+    ![GitLab token type selection showing Legacy and Fine-grained options](/images/code-reviews/pr-reviews/pr-reviews-gitlab-05.webp)
+
 4. Enter a descriptive name (for example, "kluster.ai PR Reviews"), set an expiration date, and select the following scopes: `api`, `read_api`, and `read_user`.
+
+    ![GitLab token form with api, read_api, and read_user scopes selected](/images/code-reviews/pr-reviews/pr-reviews-gitlab-06.webp)
+
 5. Click **Generate token**, then copy the token immediately. The token value is only displayed once and cannot be retrieved later.
 
 ??? note "Alternative: fine-grained personal access token (Beta)"
     If you want to restrict kluster to specific repositories, you can use a fine-grained personal access token instead. Fine-grained tokens let you choose exactly which projects kluster can access, but you must manually enable every required permission.
 
     To create a fine-grained token:
 
-    1. On the [Personal access tokens](https://gitlab.com/-/user_settings/personal_access_tokens){target=\_blank} page, click **Add new token** and select **Fine-grained token (Beta)**.
+    1. On the [Personal access tokens](https://gitlab.com/-/user_settings/personal_access_tokens){target=\_blank} page, click **Generate token** and select **Fine-grained token (Beta)**.
     2. Enter a descriptive name and set an expiration date.
     3. Under **Group and project permissions**, enable the following scopes: