docs: add Slack assistant, MCP and pentest API guides

api-reference/archives/request-archive-upload.mdx

@@ -0,0 +1,20 @@
+---
+title: "Request archive upload"
+openapi: "POST /archives/uploads"
+description: "Get a URL to upload a code archive to, for code that isn't in a connected repository."
+---
+
+Returns a signed URL for uploading a `.zip`, `.7z` or `.tar.gz` source archive.
+
+<Info>**Scope required**: `write`. **Role**: member or above.</Info>
+
+1. Call this endpoint with the archive's `file_name`.
+2. `PUT` the file to `upload_url`, with the `Content-Type` header set to the returned `content_type`.
+3. Add `{ "source": "upload", "archive_id": "<id>" }` to `repos` when you [create a pentest draft](/api-reference/pentests/create-pentest).
+
+To assess part of the archive, set `include_paths` or `exclude_paths` on its entry in `repos`. You can use the same uploaded archive.
+
+<Note>
+  Some self-hosted deployments return `400` because they don't support API
+  uploads. In that case, upload the archive through the Hacktron web app.
+</Note>

api-reference/credits/get-credit-balance.mdx

@@ -0,0 +1,9 @@
+---
+title: "Get credit balance"
+openapi: "GET /credits"
+description: "Read the organization's pentest credit balance."
+---
+
+Returns the pentest credits available to the organization, with totals purchased, used, refunded and granted. `is_unlimited` is true for organizations without a credit limit.
+
+<Info>**Scope required**: `read`</Info>

api-reference/findings/count-findings.mdx

@@ -0,0 +1,9 @@
+---
+title: "Count findings"
+openapi: "GET /findings/counts"
+description: "Count findings by severity, state and repository."
+---
+
+Counts findings using the same filters as [List findings](/api-reference/findings/list-findings), without requiring you to fetch every page. The response includes the total and counts by severity, state and repository. Severity and state counts include zero values. Repositories appear in order of finding count, highest first.
+
+<Info>**Scope required**: `read`</Info>

api-reference/pentests/check-pentest-logins.mdx

@@ -0,0 +1,17 @@
+---
+title: "Check pentest logins"
+openapi: "POST /pentests/{id}/login-checks"
+description: "Check that Hacktron can sign in to each login target before the pentest starts."
+---
+
+Checks whether Hacktron can sign in to each of the draft's `login_targets` using the saved login instructions. Every login check must pass before the pentest can start.
+
+<Info>**Scope required**: `write`. **Role**: member or above.</Info>
+
+- A successful check is valid for one hour. Start the pentest within that time or run the check again.
+- Hacktron skips checks that are already running or passed within the last hour, unless the site or login instructions have changed.
+- Set `wait_seconds` to wait up to 50 seconds for the checks. Without it, the endpoint returns while checks are `pending`. You can call again with `wait_seconds` to wait for the results. Each call retries failed logins, so update incorrect instructions before calling again.
+
+Each entry in `login_targets` includes a `login_check` status: `pending` or `running` while the check is in progress, `succeeded` after a successful sign-in, or `failed` if Hacktron couldn't sign in.
+
+A failed check includes a `failure_reason` without login details. Correct the instructions with [Update pentest draft](/api-reference/pentests/update-pentest), then run the check again.

api-reference/pentests/create-pentest.mdx

@@ -0,0 +1,31 @@
+---
+title: "Create pentest draft"
+openapi: "POST /pentests"
+description: "Create a pentest that hasn't started, from repositories or uploaded archives, optionally with live sites."
+---
+
+Creates a draft with the code you want to review and any deployed sites you want to test. Creating a draft does not run a pentest or spend credits. You review the estimate before [starting it](/api-reference/pentests/start-pentest).
+
+<Info>**Scope required**: `write`. **Role**: member or above.</Info>
+
+## Set up and start a pentest
+
+1. Create the draft with this endpoint, and change it with [Update pentest draft](/api-reference/pentests/update-pentest).
+2. If the draft has `login_targets`, run [Check pentest logins](/api-reference/pentests/check-pentest-logins) until each login passes.
+3. Get the credit cost with [Estimate pentest](/api-reference/pentests/estimate-pentest).
+4. Start it with [Start pentest](/api-reference/pentests/start-pentest), or delete it with [Discard pentest draft](/api-reference/pentests/discard-pentest).
+
+Save the `scan_id` from the response. Use the same ID throughout setup and after the pentest starts, including when calling [Get scan](/api-reference/scans/get-scan).
+
+## What to test
+
+- `repos` (at least one): connected repositories, public repositories, or archives uploaded with [Request archive upload](/api-reference/archives/request-archive-upload). Set a repository's `include_paths` and `exclude_paths` to review only part of the code.
+- `target_urls`: deployed sites to test without signing in.
+- `login_targets`: deployed sites to test signed in. Each has a `site` and `login_instructions`: the login page, username, password and any extra steps. Login instructions are stored encrypted and never returned.
+
+A draft can have `target_urls` or `login_targets`, but not both. To test sites with and without a login, create separate pentests.
+
+<Note>
+  Signed-in testing is enabled per organization. If it isn't enabled for yours,
+  a request with `login_targets` returns `400`.
+</Note>

api-reference/pentests/discard-pentest.mdx

@@ -0,0 +1,9 @@
+---
+title: "Discard pentest draft"
+openapi: "DELETE /pentests/{id}"
+description: "Delete a pentest that hasn't started."
+---
+
+Deletes a draft pentest and its saved login details. To end a pentest that has already started, use [Stop scan](/api-reference/scans/stop-scan).
+
+<Info>**Scope required**: `write`. **Role**: member or above.</Info>

api-reference/pentests/estimate-pentest.mdx

@@ -0,0 +1,13 @@
+---
+title: "Estimate pentest"
+openapi: "POST /pentests/{id}/estimate"
+description: "Price a draft pentest before starting it."
+---
+
+Starts a cost estimation for the draft and returns its `cost_estimation_id`. Poll [Get cost estimation](/api-reference/cost-estimations/get-cost-estimation) until its `status` is `completed` or `partial`.
+
+<Info>**Scope required**: `write`. **Role**: member or above.</Info>
+
+When you [start the pentest](/api-reference/pentests/start-pentest), confirm the estimate's `total_credits`. Add `triage_fee_credits` if `triage_required` is true or you opt in to triage.
+
+Estimate again whenever you change the draft.

api-reference/pentests/start-pentest.mdx

@@ -0,0 +1,14 @@
+---
+title: "Start pentest"
+openapi: "POST /pentests/{id}/start"
+description: "Start an estimated pentest and spend the confirmed credits."
+---
+
+Starts a draft pentest that has a completed estimate. Credits are deducted when it starts.
+
+<Info>**Scope required**: `write`. **Role**: organization admin.</Info>
+
+- Set `expected_credits` to the estimate's `total_credits`, plus `triage_fee_credits` if triage is required or you set `triage_enabled`. If the current cost differs from this total, the endpoint returns `409` without spending credits. If the organization has insufficient credits, it returns `402`.
+- Every login target needs a login check that passed within the last hour. See [Check pentest logins](/api-reference/pentests/check-pentest-logins).
+
+After it starts, follow the pentest with [Get scan status](/api-reference/scans/get-scan-status) using the same `scan_id`, read its results with [List scan findings](/api-reference/scans/list-scan-findings), or stop it with [Stop scan](/api-reference/scans/stop-scan).

api-reference/pentests/update-pentest.mdx

@@ -0,0 +1,16 @@
+---
+title: "Update pentest draft"
+openapi: "PATCH /pentests/{id}"
+description: "Change a pentest that hasn't started."
+---
+
+Updates a draft pentest. Fields in the request replace their saved values. Omitted fields keep their current values. You can't change a pentest after it starts.
+
+<Info>**Scope required**: `write`. **Role**: member or above.</Info>
+
+- `repos` replaces the saved repository list and must contain at least one entry. Changing it clears the estimate.
+- `login_targets` replaces the full list. Send `[]` to remove all login targets. Sending the same site and login instructions preserves a successful login check. Changing either resets `login_check` to `unverified` until you check again.
+- To fix a login that failed its check, send the site again with new `login_instructions`, then run [Check pentest logins](/api-reference/pentests/check-pentest-logins).
+- To switch a draft from signed-in testing to testing without a login (or back), clear the other list in the same request, for example `"login_targets": []` with your `target_urls`.
+
+Run the estimate again after changing the draft. [Start pentest](/api-reference/pentests/start-pentest) rejects a credit total that doesn't match the current estimate.

api-reference/repos/get-pr-review-settings.mdx

@@ -0,0 +1,16 @@
+---
+title: "Get PR review settings"
+openapi: "GET /pr-review-settings"
+description: "Read how PR reviews behave across your organization."
+---
+
+Returns the PR review settings configured for your organization under **Settings** in Hacktron:
+
+- `scm_comments_enabled`: reviews post comments and finding details on pull and merge requests.
+- `scm_system_comments_enabled`: reviews also post system comments, such as skipped reviews, usage limits and configuration warnings.
+- `fail_on_severity`: the severity at or above which a finding fails the PR check, or `null` when it never fails.
+- `scan_include_*` and `scan_exclude_*`: which pull requests are reviewed, by target branch, label, author and title keyword. `null` means no filter.
+
+A repository's [`.hacktron/config.yaml`](/code-review/config) takes precedence over these defaults. To check whether reviews are enabled for a repository, read its `prScansEnabled` value from [List repositories](/api-reference/repos/list-repos).
+
+<Info>**Scope required**: `read`</Info>

api-reference/repos/set-pr-reviews.mdx

@@ -0,0 +1,13 @@
+---
+title: "Turn PR reviews on or off"
+openapi: "POST /repos/pr-reviews"
+description: "Turn automatic pull and merge request reviews on or off for repositories."
+---
+
+Enables automatic pull and merge request reviews for repositories in `enable` and disables them for repositories in `disable`. Use repository IDs from [List repositories](/api-reference/repos/list-repos) for any supported provider. Each list can contain up to 100 IDs per request.
+
+<Info>**Scope required**: `write`. **Role**: organization admin.</Info>
+
+- First, enable Hacktron access to the repository from **Repositories** in Hacktron.
+- If one repository fails, Hacktron continues with the others. The response reports how many changed in `processed` and lists failures with their reasons in `failedRepositories`.
+- `webhookPending` lists enabled repositories whose provider webhook is still pending registration. Reviews begin once the webhook is registered.

api-reference/repos/update-pr-review-settings.mdx

@@ -0,0 +1,13 @@
+---
+title: "Update PR review settings"
+openapi: "PATCH /pr-review-settings"
+description: "Change how PR reviews behave across your organization."
+---
+
+Updates your organization's PR review settings and returns the full settings object. Only fields in the request change. Send `null` to disable `fail_on_severity` or clear a filter.
+
+<Info>**Scope required**: `write`. **Role**: organization admin.</Info>
+
+Each filter replaces the saved list. To add a branch without removing existing entries, first read [Get PR review settings](/api-reference/repos/get-pr-review-settings), then send the full list with your addition.
+
+Branch and author filters take glob patterns (`*`, `**`, `?`, `{a,b}`) and are case-insensitive. Each filter holds up to 50 entries.

api-reference/scans/stop-scan.mdx

@@ -0,0 +1,9 @@
+---
+title: "Stop scan"
+openapi: "POST /scans/{id}/stop"
+description: "Stop a running scan or pentest."
+---
+
+Stops a running scan and returns its status. Members can stop their own pentests and any PR scan. Organization admins can stop any scan.
+
+<Info>**Scope required**: `write`. **Role**: member or above.</Info>

code-review/integrations/slack.mdx

@@ -27,20 +27,18 @@
 
 ## Link your Slack identity
 
-To perform actions on findings directly from Slack and for Hacktron to tag
-you on Slack, you need to link your Slack identity to your Hacktron account
-so that Hacktron can recognize you on Slack.
+Link your Slack and Hacktron accounts so you can update findings from Slack
+and Hacktron can mention you in notifications.
 
 <Steps>
-  <Step title="Open Account page">
-    Click on your organization name in the top left corner and go to
-    **Account**.
+  <Step title="Open Personal settings">
+    Open **Personal settings** in Hacktron.
   </Step>
   <Step title="Connect Slack">
-    Scroll down to **Connected Accounts** and click on **Connect** next to
+    Find **Connected accounts** and click **Connect** next to
     **Slack**.
 
-    <img src="/images/connected_accounts.png" alt="Connected Accounts" />
+    <img src="/images/slack-connected-accounts.png" alt="Connected accounts in Personal settings, with a Connect button next to Slack" />
 
   </Step>
   <Step title="Authorize Hacktron">
@@ -57,16 +55,16 @@
 
   </Step>
   <Step title="Return to Hacktron">
-    After authorization, Hacktron redirects you back to **Account**.
+    After authorization, Hacktron redirects you back to **Personal settings**.
   </Step>
 </Steps>
 
-You can now provide feedback and act on findings directly from Slack.
+You can now provide feedback and update findings from Slack. To ask about findings, prepare a pentest or manage PR reviews, [mention @Hacktron AI](/platform/slack-assistant).
 
 <Card
   title="Findings and feedback"
   icon="message-dots"
   href="/code-review/findings-feedback"
 >
   Understand how feedback you give Hacktron improves future reviews.
 </Card>

docs.json

@@ -27,6 +27,10 @@
             "group": "Overview",
             "pages": ["index", "platform/overview", "platform/dashboard"]
           },
+          {
+            "group": "Assistant",
+            "pages": ["platform/slack-assistant"]
+          },
           {
             "group": "Setup",
             "pages": [
@@ -188,13 +192,31 @@
               "api-reference/scans/get-scan",
               "api-reference/scans/get-scan-status",
               "api-reference/scans/list-scan-findings",
-              "api-reference/scans/export-scan-findings"
+              "api-reference/scans/export-scan-findings",
+              "api-reference/scans/stop-scan"
+            ]
+          },
+          {
+            "group": "Pentests",
+            "pages": [
+              "api-reference/pentests/create-pentest",
+              "api-reference/pentests/update-pentest",
+              "api-reference/pentests/check-pentest-logins",
+              "api-reference/pentests/estimate-pentest",
+              "api-reference/pentests/start-pentest",
+              "api-reference/pentests/discard-pentest",
+              "api-reference/archives/request-archive-upload"
             ]
           },
+          {
+            "group": "Credits",
+            "pages": ["api-reference/credits/get-credit-balance"]
+          },
           {
             "group": "Findings",
             "pages": [
               "api-reference/findings/list-findings",
+              "api-reference/findings/count-findings",
               "api-reference/findings/get-finding",
               "api-reference/findings/update-finding",
               "api-reference/findings/add-finding-comment",
@@ -203,7 +225,12 @@
           },
           {
             "group": "Repositories",
-            "pages": ["api-reference/repos/list-repos"]
+            "pages": [
+              "api-reference/repos/list-repos",
+              "api-reference/repos/set-pr-reviews",
+              "api-reference/repos/get-pr-review-settings",
+              "api-reference/repos/update-pr-review-settings"
+            ]
           },
           {
             "group": "Dependency Firewall",