Automation (remediation) documentation

code-review/config.mdx

@@ -1,12 +1,13 @@
 ---
 title: "Repository configuration"
-description: "Use .hacktron/config.yaml to control which pull and merge requests Hacktron scans, and when a finding should fail the check."
+description: "Use .hacktron/config.yaml to control which pull and merge requests Hacktron scans, when a finding should fail the check, and whether findings are remediated automatically."
 ---
 
 Add a `.hacktron/config.yaml` file to your repository to control Hacktron's Code Review behavior:
 
 - **Skip** specific pull and merge requests so they aren't scanned.
 - **Fail** the Hacktron check when a finding meets a severity threshold, so risky changes can't merge.
+- **Auto-remediate** findings at or above a severity, so qualifying findings get an AI-generated fix PR automatically.
 
 This is separate from [`.hacktron/rules.md`](/code-review/rules), which shapes the *quality* of a review. `config.yaml` controls *whether* a PR is scanned and *whether* its check passes.
 
@@ -51,9 +52,14 @@ skip:
 # Fail the Hacktron check when a finding is at or above this severity.
 fail_on:
   severity: high
+
+# Automatically remediate findings at or above this severity.
+remediation:
+  auto: true
+  severity: high
 ```
 
-Every key is optional. An empty or absent `config.yaml` means Hacktron behaves as it does today: it scans all covered PRs and the check stays green unless the scan itself errors.
+Every key is optional. An empty or absent `config.yaml` means Hacktron scans all covered PRs and the check stays green unless the scan itself errors. It does **not** turn off auto-remediation, though: a repository without a `remediation` block follows your organization's enabled [automations](/platform/automations/overview), which can start credit-consuming remediation runs for its findings. To opt a repository out, set [`remediation.auto: false`](#auto-remediate-findings) instead of omitting the block.
 
 ## Skip scans
 
@@ -139,11 +145,34 @@ You can set the threshold org-wide from the settings page, or per repository in
   </Tab>
 </Tabs>
 
+## Auto-remediate findings
+
+Add a `remediation` block to have Hacktron [remediate](/platform/automations/remediation) qualifying findings in this repository automatically. When a finding at or above the configured severity is reported, Hacktron starts a remediation run: an agent writes a fix and opens a pull or merge request with it.
+
+```yaml
+remediation:
+  auto: true       # turn auto-remediation on for this repository
+  severity: high   # remediate findings at or above this severity
+```
+
+- `auto` turns auto-remediation on (`true`) or off (`false`) for the repository.
+- `severity` is **inclusive** and uses the same levels as `fail_on.severity`: `critical` › `high` › `medium` › `low` › `info`. When omitted, it defaults to `critical`.
+
+Each auto-triggered run consumes [automation credits](/platform/automations/credits), so pick a threshold that matches how much you want remediated automatically. Each finding is remediated at most once.
+
+<Note>
+  A repository with a `remediation` block follows that block **exclusively**:
+  `auto: false` also turns off any organization
+  [automations](/platform/automations/overview) for this repository.
+  Repositories without a `remediation` block follow the organization's enabled
+  automations instead.
+</Note>
+
 ## How invalid config is handled
 
 Hacktron is **fail-open** about configuration — a config problem never silently blocks your development:
 
-- A missing, empty, or malformed `config.yaml` is ignored. Hacktron scans normally and the check stays green.
+- A missing, empty, or malformed `config.yaml` is ignored. Hacktron scans normally and the check stays green. Because an ignored config has no `remediation` block, the repository follows your organization's enabled [automations](/platform/automations/overview).
 - Unknown keys are ignored, so a config can carry settings for future features without breaking today's scans.
 - A type mismatch on a known key (for example `fail_on.severity: 7`) causes the **whole file** to be ignored. Keep values in the shapes shown above.
 
@@ -156,4 +185,10 @@ Hacktron is **fail-open** about configuration — a config problem never silentl
   <Card title="Setup" icon="code-branch" href="/code-review/setup">
     Connect a Git provider, enable repositories, and choose covered branches.
   </Card>
+  <Card title="Remediation" icon="wrench" href="/platform/automations/remediation">
+    How a remediation run works and where the fix PR lands.
+  </Card>
+  <Card title="Automations" icon="bolt" href="/platform/automations/overview">
+    Auto-remediate findings org-wide with notifications and run history.
+  </Card>
 </Columns>

code-review/findings-feedback.mdx

@@ -119,6 +119,12 @@ If a [fail-on gate](/code-review/config#fail-the-check-on-findings) is configure
 For example, if the fail-on gate is configured to fail on high severity findings, triaging a high severity finding as a false positive
 or accepted risk will update the GitHub check (or GitLab commit status) to pass. Reopening the finding will cause the check to fail again.
 
+## Remediate a finding
+
+Hacktron can also fix a finding for you. Select **Remediate** on a finding in the web platform and a Hacktron agent writes a fix and opens a pull or merge request with it. You can also remediate qualifying findings automatically with [automations](/platform/automations/overview) or [repository configuration](/code-review/config#auto-remediate-findings).
+
+See [Remediation](/platform/automations/remediation) for how runs work, where the fix lands, and billing.
+
 ## Feedback loop
 
 Triage feedback helps Hacktron adapt to your codebase. Comments and project rules

docs.json

@@ -69,6 +69,14 @@
               "platform/context/threat-models"
             ]
           },
+          {
+            "group": "Automations",
+            "pages": [
+              "platform/automations/overview",
+              "platform/automations/remediation",
+              "platform/automations/credits"
+            ]
+          },
           {
             "group": "Account",
             "pages": [

platform/account-settings.mdx

@@ -3,8 +3,7 @@ title: "Account settings"
 description: "Manage your Hacktron profile and personal account security."
 ---
 
-Use **Account settings** to manage your personal profile and your own Hacktron
-account security. Open it from the account menu in the sidebar header.
+Use **Account settings** to manage your personal profile and your own Hacktron account security. Open it from the account menu in the sidebar header.
 
 ## Profile
 
@@ -16,53 +15,39 @@ Your profile controls how you appear to the rest of your organization.
 
 ## Multi-factor authentication (MFA)
 
-Multi-factor authentication adds a second verification step to sign-in, so a
-password alone is not enough to access your account. We strongly recommend
-enabling MFA on every account.
+Multi-factor authentication adds a second verification step to sign-in, so a password alone is not enough to access your account. We strongly recommend enabling MFA on every account.
 
 ### Enable MFA
 
 <Steps>
   <Step title="Open Account settings">
     Open the account menu in the sidebar header and select **Account settings**.
 
-    <img src="/images/mfa_enable.png" alt="Enable MFA from Account settings" />
-
+    ![Enable MFA from Account settings](/images/mfa_enable.png)
   </Step>
   <Step title="Start MFA setup">
     Select **Enable MFA**. Hacktron shows a QR code for your authenticator app.
   </Step>
   <Step title="Add Hacktron to your authenticator app">
-    Scan the QR code with an authenticator app such as 1Password, Google
-    Authenticator, or Authy. If you cannot scan it, enter the setup key manually.
+    Scan the QR code with an authenticator app such as 1Password, Google Authenticator, or Authy. If you cannot scan it, enter the setup key manually.
   </Step>
   <Step title="Confirm the code">
-    Enter the 6-digit code from your authenticator app to confirm setup. After it
-    is verified, MFA is required the next time you sign in.
+    Enter the 6-digit code from your authenticator app to confirm setup. After it is verified, MFA is required the next time you sign in.
   </Step>
 </Steps>
 
-<Card
-  title="Organization-wide security controls"
-  icon="shield-check"
-  href="/platform/security-settings"
->
-  Organization-wide security controls are managed separately from personal
-  account settings.
+<Card title="Organization-wide security controls" icon="shield-check" href="/platform/security-settings">
+  Organization-wide security controls are managed separately from personal account settings.
 </Card>
 
 ### Save your backup codes
 
-When you enable MFA, Hacktron generates one-time backup codes. Store them in a
-safe place such as a password manager.
+When you enable MFA, Hacktron generates one-time backup codes. Store them in a safe place such as a password manager.
 
 <Warning>
-  Backup codes are the only way to sign in if you lose access to your
-  authenticator app. Save them somewhere secure and do not share them.
+  Backup codes are the only way to sign in if you lose access to your authenticator app. Save them somewhere secure and do not share them.
 </Warning>
 
 ### Disable or reset MFA
 
-You can turn MFA off or re-run setup from **Account settings**. Disabling MFA
-weakens your account security, so only do this if you are switching to a new
-device or authenticator app.
+You can turn MFA off or re-run setup from **Account settings**. Disabling MFA weakens your account security, so only do this if you are switching to a new device or authenticator app.

platform/automations/credits.mdx

@@ -0,0 +1,74 @@
+---
+title: "Automation credits"
+description: "Understand how you buy automation credit, how each run deducts them, and how auto top-up keeps your balance stocked."
+---
+
+[Automations](/platform/automations/overview) run on shared organization automation credits. Every [remediation](/platform/automations/remediation) run, whether triggered manually from a finding or by an automation, deducts credits based on what the run costs when it completes.
+
+Automation credits are organization-wide. They are separate from Code Review seats and your Whitebox Scan credits.
+
+## How credits work
+
+<Steps>
+  <Step title="Keep a balance">
+    <Tip>
+      All organizations with an active [Code Review](/code-review/overview)
+      subscription start with $50 in automation credits.
+    </Tip>
+    Buy credits from **Billing**, or turn on auto top-up to keep the balance above
+    a threshold you set.
+  </Step>
+  <Step title="Runs check the balance">
+    A remediation run only starts while the organization has credits. When the
+    balance runs out, new runs don't start and the Billing page shows that
+    automations are paused.
+  </Step>
+  <Step title="Runs deduct on completion">
+    Each run's cost is deducted from the balance once, when the run completes.
+    Costs vary with the size of the run.
+  </Step>
+</Steps>
+
+## Buy credits
+
+Organization **Owners** can buy automation credits from **Billing**. A saved payment method is required; if the organization has none, add one first.
+
+<Steps>
+  <Step title="Open Billing">
+    Go to **Billing** in the Hacktron dashboard and find your automation credit
+    balance.
+  </Step>
+  <Step title="Choose an amount">
+    Select **Buy credits**, enter the credit amount, and review the price shown.
+  </Step>
+  <Step title="Complete checkout">
+    Complete any required card authentication (such as 3D Secure). The purchased
+    credits are added to the organization balance after the charge succeeds.
+  </Step>
+</Steps>
+
+The Billing page shows the credit balance and recent activity: purchases, run deductions, and grants.
+
+## Auto top-up
+
+Auto top-up buys credits automatically when the balance drops below a threshold, so yourautomations keep running without manual purchases.
+
+Set it up on the Billing page under your automation credit balance:
+
+- **Trigger**: the balance that starts a top-up.
+- **Target**: the balance the top-up buys back up to. Your target must be above the trigger.
+- **Monthly limit**: an optional cap on how many credits auto top-up may buy per month.
+
+Auto top-up requires a saved payment method and charges the card on file without an interactive checkout. If a top-up charge fails, your automations stay paused until the balance is topped up manually or the card issue is resolved.
+
+## Related docs
+
+<Columns cols={2}>
+  <Card title="Remediation" icon="wrench" href="/platform/automations/remediation">
+    Trigger an AI-generated fix for a finding.
+  </Card>
+
+  <Card title="Automations" icon="bolt" href="/platform/automations/overview">
+    Auto-remediate qualifying findings and notify your team.
+  </Card>
+</Columns>

platform/automations/overview.mdx

@@ -0,0 +1,91 @@
+---
+title: "Automations"
+description: "Act on findings automatically. Set the rules for which findings qualify, and Hacktron fixes them the moment they're reported, then alerts your team. "
+---
+
+Automations act on findings for you. Configure which findings qualify, and when a matching finding is reported, Hacktron fires the automation: its **actions** run against the finding, and its **notifiers** alert your team over Slack or email.
+
+<Tip>
+  **Autofix** is the first available action — it starts a [remediation](/platform/automations/remediation) run that fixes the finding — and we'll expand automations with more actions over time.
+</Tip>
+
+Automations live under **Automations** in the dashboard sidebar. Organization **Admins** create and manage automations; other members can view them.
+
+## Create an automation
+
+<Steps>
+  <Step title="Create">
+    On the **Automations** page, select **New automation** and give it a name.
+
+    ![New automation](/images/autofix-1.png)
+  </Step>
+  <Step title="Pick environments">
+    Choose the repositories and [applications](/platform/context/applications) the automation covers. You can limit each entry to specific branches (up to two) or leave the branch selection empty to cover all branches.
+
+    ![Pick environments](/images/autofix-2.png)
+  </Step>
+  <Step title="Configure settings">
+    On the **Settings** tab, set:
+
+    - **Triggers**: when the automation runs, for example a PR scan finding, it's narrowed by the rules you set, the severity levels that qualify, and scope rules that limit it to specific repositories or applications.
+    - **Actions**: what the automation does. **Autofix** starts a [remediation](/platform/automations/remediation) run for the matching finding.
+    - **Notifiers**: who hears about a run, whether it's a Slack channel, email recipients from your organization's members, or both.
+
+    ![Configure settings](/images/autofix-3.png)
+  </Step>
+  <Step title="Save">
+    Select **Save**. An automation needs at least one environment, one trigger, and one action to run. Incomplete automations show an **Incomplete** badge and cannot be enabled. A save that removes required configuration disables the automation until it is complete again.
+  </Step>
+</Steps>
+
+## When an automation fires
+
+When a new finding is reported, an enabled automation fires if the finding matches its trigger, severity rules, scope rules, and one of its environments (including any branch limits). Firing runs the automation's actions — an **Autofix** action starts a remediation run, which uses [automation credits](/platform/automations/credits) — and sends your notifications.
+
+Each finding is fixed at most once, a finding that already has a remediation run won't fire automations again.
+
+<Info>
+  A repository with a `remediation` block in its [`.hacktron/config.yaml`](/code-review/config#auto-remediate-findings) follows that block exclusively, including `auto: false`, which turns auto-remediation off for that repository. Organization automations apply only to repositories without a `remediation` block.
+</Info>
+
+### Notifications
+
+- **Slack**: Hacktron posts a message to your channel linking the finding. The Hacktron bot joins public channels automatically; for a private channel, invite the bot to the channel first.
+- **Email**: Hacktron emails the recipients you choose from your organization's members.
+
+Notifications are best-effort, if one fails to send, it never blocks the remediation run itself. 
+
+## Run history
+
+The **Run history** tab lists every run your automation has fired, with its status, the environment it matched, and the credits it used. Runs matched through an application are attributed to that application.
+
+Run statuses mirror [remediation outcomes](/platform/automations/remediation#outcomes): **Running**, **Success**, **No fix needed**, **False positive**, and **Failed**. You can filter the history by status and search it.
+
+<img
+  src="/images/run-history.png"
+  alt="Image"
+  title="Image"
+  lightAlt="Run history"
+  darkAlt="Run history"
+  className="dark:hidden"
+/>
+<img
+  src="/images/image.png"
+  alt="Image"
+  title="Image"
+  lightAlt="Run history"
+  darkAlt="Run history"
+  className="hidden dark:block"
+/>
+
+## Related docs
+
+<Columns cols={2}>
+  <Card title="Remediation" icon="wrench" href="/platform/automations/remediation">
+    How a remediation run works and where the fix lands.
+  </Card>
+
+  <Card title="Automation credits" icon="coins" href="/platform/automations/credits">
+    How runs are billed and how to keep a balance with auto top-up.
+  </Card>
+</Columns>