Automation (remediation) documentation

code-review/billing.mdx

@@ -1,78 +1,57 @@
 ---
-title: "Trial and billing"
-description: "Understand Code Review payment methods, trials, seats, and subscription lifecycle."
+title: "Code Review Billing"
+description: "Free trial, seats, spillover, and subscription lifecycle for Code Review."
 ---
 
-Code Review billing is based on Code Review seats. A seat covers one developer whose pull requests or merge requests can be reviewed by Hacktron.
+Each developer with Code Review enabled counts as one seat. Seats can be assigned manually, or Hacktron can assign seats automatically when developers open pull requests in covered repositories.
 
-Organization owners manage payment methods, invoices, billing details, subscription state, and promotion codes from **Billing**.
+Code Review is billed as a monthly subscription. At the end of each billing period, your organization is charged for the number of seats that were active during that period.
 
-## Start a trial
+<Info>
+  If a developer no longer needs Code Review, remove their seat from **People**.
+
+  The removed seat can be reassigned to someone else during the same billing period, but removing a seat in the middle of the billing period will not reduce the seat count for that period.
+</Info>
 
-Code Review has a free trial for new organizations.
+## Start your Free Trial
 
 <Steps>
-  <Step title="Open Billing">Go to **Billing** as an organization owner.</Step>
-  <Step title="Start the trial">
-    Review and accept the terms of service and start the trial. No payment method
-    is required during the free trial.
+  <Step title="Open Billing">
+    Open Billing from the side bar. You must be an organization owner to see this. 
+
+    ![Billing Dashboard](/images/billing-dashboard-1.png)
+  </Step>
+  <Step title="Start the Code Review Trial">
+    Review and accept the terms of service and start the trial. No payment method is required during the free trial.
   </Step>
-  <Step title="Start the Code Review trial">
-    Once the trial is active, Hacktron starts running code reviews on all
-    covered repositories.
+  <Step title="Done!">
+    Once the trial is active, Hacktron starts running code reviews on all covered repositories.
   </Step>
 </Steps>
 
-## How seats are billed
-
-Each developer with Code Review enabled counts as one Code Review seat.
-Seats can be assigned manually, or Hacktron can assign seats automatically
-when developers open pull requests in covered repositories.
-
-Code Review is billed as a monthly subscription. At the end of each billing period,
-your organization is charged for the number of Code Review seats that were active
-during that period.
+## End Trial Early
 
-<Info>
-  If a developer no longer needs Code Review, remove their seat from **People**.
-
-The removed seat can be reassigned to someone else during the same billing period,
-but removing a seat in the middle of the billing period will not reduce the
-seat count for the current billing period.
-
-</Info>
-
-## End a trial early
-
-Ending the trial early allows you to start the paid plan immediately and enable [spillover usage](/code-review/spillover-usage).
+Ending the trial early allows you to start the paid plan immediately and enable [**spillover usage**](https://docs.hacktron.ai/code-review/spillover-usage).
 
 <Steps>
-  <Step title="Open Billing">Go to **Billing** as an organization owner.</Step>
   <Step title="End the trial early">
     Go to **Billing** and end the trial early to start the paid plan immediately.
 
-    <img src="/images/end_early.png" alt="End trial early" />
-
+    <Frame>
+      ![End trial early](/images/end_early.png)
+    </Frame>
   </Step>
   <Step title="Enable spillover">
-    Go to **Usage** to enable spillover billing to continue reviewing pull requests or merge requests
-    after the pooled review limit is reached.
+    Go to **Usage** to enable spillover billing to continue reviewing pull requests or merge requests after the pooled review limit is reached.
   </Step>
 </Steps>
 
-## Cancellations and resubscription
+## Cancellations and resubscriptions
 
-If you cancel during a trial or paid subscription, Code Review remains available
-until the end of the current trial or billing period. After cancellation takes effect,
-new pull requests or merge requests are no longer reviewed.
+If you cancel during a trial or paid subscription, Code Review remains available until the end of the current trial or billing period. After cancellation takes effect, new pull requests or merge requests are no longer reviewed.
 
-If the organization resubscribes later, Code Review starts as a paid subscription.
-The free trial does not restart.
+If the organization resubscribes later, Code Review starts as a paid subscription. The free trial does not restart.
 
-<Card
-  title="Spillover and usage"
-  icon="chart-line"
-  href="/code-review/spillover-usage"
->
+<Card title="Spillover and usage" icon="chart-line" href="/code-review/spillover-usage">
   Understand pooled review limits and overage pricing.
-</Card>
+</Card>

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,11 +69,20 @@
               "platform/context/threat-models"
             ]
           },
+          {
+            "group": "Automations",
+            "pages": [
+              "platform/automations/overview",
+              "platform/automations/remediation",
+              "platform/automations/credits"
+            ]
+          },
           {
             "group": "Account",
             "pages": [
               "platform/account-settings",
-              "platform/security-settings"
+              "platform/security-settings",
+              "platform/billing"
             ]
           },
           {

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,55 @@
+---
+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** (access only for Organization Owners), and / or turn on auto top-up to keep the balance above a threshold you set. 
+
+    ![Automation](/images/automation.png)
+  </Step>
+  <Step title="Checkout">
+    Complete any required card authentication (such as 3D Secure). The purchased credits are added to the organization balance after the charge succeeds.
+  </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>
+
+## Auto top-up
+
+Auto top-up buys credits automatically when the balance drops below a threshold, so your automations 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>