diff --git a/code-reviews/faq.md b/code-reviews/faq.md
index 13baf840..575bc99a 100644
--- a/code-reviews/faq.md
+++ b/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.
+
+
+
+**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**.
+
+
+
+Your feedback helps improve detection accuracy and reduce false positives across future reviews.
### What should I do if kluster.ai flags a false positive?
diff --git a/code-reviews/pr-reviews/bitbucket.md b/code-reviews/pr-reviews/bitbucket.md
index 5bf4fbcb..9de6ccf5 100644
--- a/code-reviews/pr-reviews/bitbucket.md
+++ b/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 | ```read:account```
| View users' profiles. |
- | Account & User | ```read:user:bitbucket```
| View user info. |
- | Repository | ```read:repository:bitbucket```
| View your repositories. |
- | Repository | ```write:repository:bitbucket```
| Modify your repositories. |
- | Pull Requests | ```read:pullrequest:bitbucket```
| View your pull requests. |
- | Pull Requests | ```write:pullrequest:bitbucket```
| Modify your pull requests. |
- | Issues | ```read:issue:bitbucket```
| View your issues. |
- | Issues | ```write:issue:bitbucket```
| Modify your issues. |
- | Workspace | ```read:workspace:bitbucket```
| View your workspaces. |
- | Workspace | ```admin:project:bitbucket```
| Administer your projects. |
- | Webhooks | ```read:webhook:bitbucket```
| View your webhooks. |
- | Webhooks | ```write:webhook:bitbucket```
| Modify your webhooks. |
- | Pipelines | ```read:pipeline:bitbucket```
| View your pipelines. |
- | Pipelines | ```read:runner:bitbucket```
| 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**.
+
+ 
+
+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 | ```read:account```
| View users' profiles. |
+ | Account & User | ```read:user:bitbucket```
| View user info. |
+ | Repository | ```read:repository:bitbucket```
| View your repositories. |
+ | Repository | ```write:repository:bitbucket```
| Modify your repositories. |
+ | Pull Requests | ```read:pullrequest:bitbucket```
| View your pull requests. |
+ | Pull Requests | ```write:pullrequest:bitbucket```
| Modify your pull requests. |
+ | Issues | ```read:issue:bitbucket```
| View your issues. |
+ | Issues | ```write:issue:bitbucket```
| Modify your issues. |
+ | Workspace | ```read:workspace:bitbucket```
| View your workspaces. |
+ | Workspace | ```admin:project:bitbucket```
| Administer your projects. |
+ | Webhooks | ```read:webhook:bitbucket```
| View your webhooks. |
+ | Webhooks | ```write:webhook:bitbucket```
| Modify your webhooks. |
+ | Pipelines | ```read:pipeline:bitbucket```
| View your pipelines. |
+ | Pipelines | ```read:runner:bitbucket```
| 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
diff --git a/code-reviews/pr-reviews/gitlab.md b/code-reviews/pr-reviews/gitlab.md
index 44907f0e..bf32e38c 100644
--- a/code-reviews/pr-reviews/gitlab.md
+++ b/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,9 +38,15 @@ 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**.
+
+ 
+
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`.
+
+ 
+
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)"
@@ -48,7 +54,7 @@ The kluster.ai bot uses a **Legacy** personal access token. GitLab now shows two
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:
diff --git a/images/code-reviews/faq/faq-feedback-01.webp b/images/code-reviews/faq/faq-feedback-01.webp
new file mode 100644
index 00000000..e22aea10
Binary files /dev/null and b/images/code-reviews/faq/faq-feedback-01.webp differ
diff --git a/images/code-reviews/faq/faq-feedback-02.webp b/images/code-reviews/faq/faq-feedback-02.webp
new file mode 100644
index 00000000..3a042173
Binary files /dev/null and b/images/code-reviews/faq/faq-feedback-02.webp differ
diff --git a/images/code-reviews/pr-reviews/pr-reviews-bitbucket-05.webp b/images/code-reviews/pr-reviews/pr-reviews-bitbucket-05.webp
new file mode 100644
index 00000000..18614507
Binary files /dev/null and b/images/code-reviews/pr-reviews/pr-reviews-bitbucket-05.webp differ
diff --git a/images/code-reviews/pr-reviews/pr-reviews-gitlab-05.webp b/images/code-reviews/pr-reviews/pr-reviews-gitlab-05.webp
new file mode 100644
index 00000000..948b3c2a
Binary files /dev/null and b/images/code-reviews/pr-reviews/pr-reviews-gitlab-05.webp differ
diff --git a/images/code-reviews/pr-reviews/pr-reviews-gitlab-06.webp b/images/code-reviews/pr-reviews/pr-reviews-gitlab-06.webp
new file mode 100644
index 00000000..c49787ea
Binary files /dev/null and b/images/code-reviews/pr-reviews/pr-reviews-gitlab-06.webp differ