docs: introduce the Slack assistant and clarify customer guides

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

@@ -4,17 +4,17 @@ 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 to upload a `.zip`, `.7z` or `.tar.gz` archive of source code to.
+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. Pentest it by adding `{ "source": "upload", "archive_id": "<id>" }` to `repos` in [Create pentest draft](/api-reference/pentests/create-pentest).
+3. Add `{ "source": "upload", "archive_id": "<id>" }` to `repos` when you [create a pentest draft](/api-reference/pentests/create-pentest).
 
-To pentest only part of the archive, set `include_paths` or `exclude_paths` on that repo instead of uploading a smaller archive.
+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 installs don't support uploads through the API and return
-  `400`. Upload the archive in the Hacktron web app instead.
+  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/findings/count-findings.mdx

@@ -4,6 +4,6 @@ openapi: "GET /findings/counts"
 description: "Count findings by severity, state and repository."
 ---
 
-Counts the findings that match the same filters as [List findings](/api-reference/findings/list-findings), without paging through them. The response has the total, counts for every severity and state (zero when there are none), and counts per repository with the most findings first.
+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

@@ -4,12 +4,14 @@ openapi: "POST /pentests/{id}/login-checks"
 description: "Check that Hacktron can sign in to each login target before the pentest starts."
 ---
 
-Has Hacktron sign in to each of the draft's `login_targets` with its login instructions. Every login must pass before the pentest can start.
+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 passed check lasts one hour. Start the pentest within the hour, or check again.
-- Logins that are already being checked, or that passed within the last hour, aren't checked again unless their site or login instructions changed.
-- Set `wait_seconds` (up to 50) to wait for the checks to finish before the response returns. Without it, the response returns while the checks are `pending`. Call again with `wait_seconds` to wait for them. Each call checks failed logins again, so fix their instructions first.
+- 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` reports its `login_check`: `pending` or `running` while Hacktron signs in, `succeeded` when it signed in, and `failed` when it couldn't. A failed check has a `failure_reason`, which never includes the login details. Fix the instructions with [Update pentest draft](/api-reference/pentests/update-pentest) and check 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

@@ -4,26 +4,26 @@ openapi: "POST /pentests"
 description: "Create a pentest that hasn't started, from repositories or uploaded archives, optionally with live sites."
 ---
 
-Creates a draft pentest. A draft holds the code to review and, optionally, deployed sites to test live. Nothing runs and no credits are spent until you [start it](/api-reference/pentests/start-pentest).
+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>
 
-## Lifecycle
+## 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. Price it with [Estimate pentest](/api-reference/pentests/estimate-pentest).
+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).
 
-Keep the `scan_id` from the response. It identifies the pentest from draft to finish, so you can follow it afterwards with [Get scan](/api-reference/scans/get-scan).
+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 pentest tests its live sites either all signed in or all without a login, so one draft can't have both `target_urls` and `login_targets`. Create a separate pentest for the other kind.
+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,

api-reference/pentests/estimate-pentest.mdx

@@ -8,6 +8,6 @@ Starts a cost estimation for the draft and returns its `cost_estimation_id`. Pol
 
 <Info>**Scope required**: `write`. **Role**: member or above.</Info>
 
-The total to confirm when you [start the pentest](/api-reference/pentests/start-pentest) is the estimate's `total_credits`, plus `triage_fee_credits` when `triage_required` is true or you opt in to triage.
+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

@@ -8,7 +8,7 @@ Starts a draft pentest that has a completed estimate. Credits are deducted when
 
 <Info>**Scope required**: `write`. **Role**: organization admin.</Info>
 
-- `expected_credits` is the total you confirmed: the estimate's `total_credits`, plus `triage_fee_credits` when triage is required or you set `triage_enabled`. If the pentest now costs a different amount, the request fails with `409` and nothing is spent. Without enough credits it fails with `402`.
+- 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

@@ -4,13 +4,13 @@ openapi: "PATCH /pentests/{id}"
 description: "Change a pentest that hasn't started."
 ---
 
-Changes a draft pentest. Fields you send replace the saved values, and fields you leave out are kept. A pentest that has started can't be changed.
+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 repositories and needs at least one. Changing them clears the estimate.
-- `login_targets` replaces the whole list, and `[]` removes every login target. Resending a site with the same login instructions keeps its passed login check. A changed site or login reports `login_check: unverified` until you check it again.
+- `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`.
 
-Estimate the pentest again after changing it. [Start pentest](/api-reference/pentests/start-pentest) rejects a total that doesn't match the current estimate.
+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

@@ -4,13 +4,13 @@ openapi: "GET /pr-review-settings"
 description: "Read how PR reviews behave across your organization."
 ---
 
-Returns your organization's PR review settings, the ones under **Settings** in Hacktron:
+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) overrides these. Whether each repository has reviews turned on is `prScansEnabled` in [List repositories](/api-reference/repos/list-repos).
+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

@@ -4,10 +4,10 @@ openapi: "POST /repos/pr-reviews"
 description: "Turn automatic pull and merge request reviews on or off for repositories."
 ---
 
-Turns automatic PR and MR reviews on for the repositories in `enable` and off for those in `disable`. Use each repository's `id` from [List repositories](/api-reference/repos/list-repos), whichever provider it's on. Up to 100 of each per request.
+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>
 
-- A repository must be enabled for Hacktron access before its reviews can be turned on. Enable it from **Repositories** in Hacktron.
-- One repository failing doesn't stop the rest. The response counts the repositories that changed (`processed`) and lists each one that didn't with the reason (`failedRepositories`).
-- `webhookPending` lists repositories that were turned on but whose provider webhook couldn't be registered yet. Reviews start once it is.
+- 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

@@ -4,10 +4,10 @@ openapi: "PATCH /pr-review-settings"
 description: "Change how PR reviews behave across your organization."
 ---
 
-Changes your organization's PR review settings and returns all of them. Only the fields you send change. Send `null` to turn off `fail_on_severity` or clear a filter.
+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>
 
-A filter is replaced as a whole. To add one branch, read the settings with [Get PR review settings](/api-reference/repos/get-pr-review-settings) first and send the full list.
+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

@@ -4,6 +4,6 @@ openapi: "POST /scans/{id}/stop"
 description: "Stop a running scan or pentest."
 ---
 
-Stops a scan that is running and returns its status. Members can stop pentests they started and any PR scan, and organization admins can stop any scan.
+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

@@ -61,7 +61,7 @@ so that Hacktron can recognize you on Slack.
   </Step>
 </Steps>
 
-You can now provide feedback and act on findings directly from Slack, and [ask Hacktron in Slack](/platform/communication-apps/slack-agent) as yourself.
+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"

docs.json

@@ -27,6 +27,10 @@
             "group": "Overview",
             "pages": ["index", "platform/overview", "platform/dashboard"]
           },
+          {
+            "group": "Assistant",
+            "pages": ["platform/slack-assistant"]
+          },
           {
             "group": "Setup",
             "pages": [
@@ -55,8 +59,7 @@
                 "group": "Communication Apps",
                 "pages": [
                   "platform/communication-apps",
-                  "platform/communication-apps/slack",
-                  "platform/communication-apps/slack-agent"
+                  "platform/communication-apps/slack"
                 ]
               }
             ]