amplify-security · ogael-amplify · Aug 3, 2026
diff --git a/README.md b/README.md
@@ -1,32 +1,65 @@
-# Mintlify Starter Kit
+# Amplify Security docs
 
-Click on `Use this template` to copy the Mintlify starter kit. The starter kit contains examples including
+Documentation site for [Amplify Security](https://github.com/amplify-security), built with
+[Mintlify](https://mintlify.com/). Configuration lives in `docs.json`.
 
-- Guide pages
-- Navigation
-- Customizations
-- API Reference pages
-- Use of popular components
+## Structure
 
-### Development
+The site has two tabs. **Amplify Console** is the current product, organized into three ideas that build
+on each other:
 
-Install the [Mintlify CLI](https://www.npmjs.com/package/mintlify) to preview the documentation changes locally. To install, use the following command
+| Group | Covers |
+| --- | --- |
+| `Get Started` | Introduction, quickstart, CLI installation |
+| `The Harness` (`harness/`) | The authorable primitives — agents, skills, detections — and the tool surface |
+| `Context` (`context/`) | Projects, connections, vendor data, findings |
+| `Working interactively` (`interactive/`) | Chat and the CLI |
+| `Workflows` (`workflows/`) | Creating, triggering, running, and delivering workflow results |
 
-```
-npm i -g mintlify
+**Amplify Dashboard (Legacy)** (`legacy/`) documents the previous product and is not actively developed.
+
+## Development
+
+Install the Mintlify CLI:
+
+```bash
+npm i -g mint
 ```
 
-Run the following command at the root of your documentation (where mint.json is)
+Run the dev server from the repository root (the directory containing `docs.json`):
 
+```bash
+mint dev
 ```
-mintlify dev
+
+It serves on port 3000 by default. Use `--port` if that's taken:
+
+```bash
+mint dev --port 3333
 ```
 
-### Publishing Changes
+## Adding a page
+
+1. Create the `.mdx` file in the appropriate directory, with `title` and `description` frontmatter.
+2. Register its path (without the `.mdx`) in the correct group in `docs.json`. **A page not listed in
+   `docs.json` will not appear in the navigation.**
+3. If you move or rename a page, add a `redirects` entry in `docs.json` so existing links keep working.
+
+## Conventions
+
+- Frontmatter requires `title` and `description`.
+- Mintlify components in use: `<Note>`, `<Tip>`, `<Warning>`, `<CardGroup>`, `<Card>`.
+- Internal links are root-relative and omit the extension — `/harness/writing-an-agent`.
+- Document what ships today. Where a capability is partial, say so explicitly in a `<Warning>` or `<Note>`
+  rather than describing the intended end state.
+
+## Publishing
 
-Install our Github App to auto propagate changes from your repo to your deployment. Changes will be deployed to production automatically after pushing to the default branch. Find the link to install on your dashboard. 
+The Mintlify GitHub App deploys automatically on push to the default branch.
 
-#### Troubleshooting
+## Troubleshooting
 
-- Mintlify dev isn't running - Run `mintlify install` it'll re-install dependencies.
-- Page loads as a 404 - Make sure you are running in a folder with `mint.json`
+- **404 on every page** — you're not in the directory containing `docs.json`.
+- **A new page isn't in the sidebar** — it isn't registered in `docs.json`.
+- **`mint` not found** — install with `npm i -g mint`. Note the CLI is `mint`, not the older `mintlify`
+  package, and configuration is `docs.json`, not the older `mint.json`.
diff --git a/context/connections.mdx b/context/connections.mdx
@@ -0,0 +1,109 @@
+---
+title: Connections
+description: 'Connect your source control provider and the security and IT vendors you already run.'
+---
+
+## Two kinds of connection
+
+The **Connections** page handles two different jobs behind one interface:
+
+| Kind | What it enables |
+| --- | --- |
+| **Source control** | Cloning repositories, pull request triggers, review comments, merge gates |
+| **Vendor connectors** | Reading signal from the security and IT tools you already run |
+
+Source control is what makes Console able to *act* on your code. Vendor connectors are what let it reason
+about findings your existing stack has already produced.
+
+## Source control
+
+### GitHub
+
+Install the Console GitHub App for your organization. You can grant access to every repository or pick a
+subset; the repositories you grant become [projects](/context/projects).
+
+The App is what powers:
+
+- Cloning repositories into sandboxes
+- [Pull request triggers](/workflows/triggers#pull-request-triggers) firing on open, reopen, and new commits
+- [Review comments](/workflows/outputs#comment-on-triggering-pull-request)
+- [Merge gates](/workflows/outputs#gate-merging-on-security-review) as required checks
+- Opening a pull request from a [finding's suggested fix](/context/findings#accepting-a-fix)
+
+See [Installation](/install-console#install-the-github-app) for the install flow.
+
+### GitLab
+
+Connect a GitLab instance by providing its host URL, the project, and a personal access token.
+
+<Note>
+  GitLab supports cloning and merge request comments. **Merge blocking is not supported yet** — a
+  [merge gate](/workflows/outputs#gitlab) on a GitLab run is recorded as skipped.
+</Note>
+
+## Vendor connectors
+
+Console connects to the security and IT tools you already run, so agents can reason about the findings
+already sitting in them.
+
+Open **Connections**, add a connection, and search the connector catalog. Connectors are grouped by
+category:
+
+| Category | Covers |
+| --- | --- |
+| **EDR** | Endpoint detection and response |
+| **AppSec** | Application security scanners — SAST, SCA, and similar |
+| **VMS** | Vulnerability management |
+| **CSPM** | Cloud security posture management |
+| **IDP** | Identity providers |
+| **GRC** | Governance, risk, and compliance |
+| **TPRM** | Third-party risk management |
+| **ITSM** | IT service management and ticketing |
+
+The catalog is searchable by vendor name or slug, and a connector spanning more than one category appears
+under each — AWS Inspector shows up under both AppSec and VMS, for instance.
+
+Completing a connection walks you through that vendor's own authorization flow. Console stores the resulting
+connection and never handles the underlying vendor API key directly — requests are brokered server-side.
+
+<Warning>
+  Connecting a vendor and *reading from it* are two different things. A connection can be established for any
+  connector in the catalog, but what an agent can query today is scoped to **vulnerability findings**. An
+  agent can read your Snyk or Semgrep backlog; it cannot read Jira issues or Cloudflare configuration.
+
+  Read [what agents can read](/context/vendor-data) before designing a workflow around a connection.
+</Warning>
+
+## Which connections do you need?
+
+| If you want to | You need |
+| --- | --- |
+| Ask an agent about your code | A source-control connection |
+| Run workflows on pull requests | GitHub |
+| Block merges on security review | GitHub |
+| Triage an existing scanner backlog against real code | An AppSec or VMS connector |
+| Just use the CLI on local code | Nothing — the CLI reads your working directory |
+
+## Troubleshooting
+
+**A repository isn't available as a project.** The GitHub App installation probably doesn't include it.
+Adjust the installation's repository access.
+
+**An output shows Failed on a run.** Confirm the App is still installed for that repository and has
+permission to write checks and pull request comments. See
+[checking delivery](/workflows/outputs#checking-delivery).
+
+**The connector catalog is empty or won't load.** The catalog is fetched when you open the dialog, so a
+transient upstream failure shows there without affecting the rest of the page. Retry.
+
+## Next steps
+
+<CardGroup cols={2}>
+  <Card title="What agents can read" icon="database" href="/context/vendor-data">
+    The exact vendor-data surface today.
+  </Card>
+
+  <Card title="Projects" icon="folder-tree" href="/context/projects">
+    Turn a connection into analyzable code.
+  </Card>
+</CardGroup>
diff --git a/context/findings.mdx b/context/findings.mdx
@@ -0,0 +1,99 @@
+---
+title: Findings
+description: 'Confirmed issues with the agent’s reasoning, the affected code, and often a ready-to-merge fix.'
+---
+
+## What a finding is
+
+A finding is a vulnerability an agent has confirmed and recorded. It's the durable output of agent work —
+what survives after the conversation or run is over.
+
+Every finding carries:
+
+- **Where** — the affected file, and the symbol it's anchored to
+- **What** — the vulnerability, its classification, and severity
+- **Why** — the agent's reasoning for believing it's genuinely exploitable
+- **The fix** — a suggested patch, when one was generated
+- **Provenance** — the run that produced it, and the [detection](/harness/detections) behind it if there was one
+
+The reasoning is the part worth reading. A pattern match tells you a shape appeared; a finding tells you why
+the agent believes an attacker can actually reach it. That's what makes it triageable.
+
+## Where findings come from
+
+| Source | How |
+| --- | --- |
+| **Workflow runs** | A scanner or detections step confirms an issue and calls `report_finding` |
+| **Chat** | An agent investigating on your behalf records what it confirms |
+| **Detections** | A stored rule matches, and the finding links back to the rule |
+| **The CLI** | Local scans record findings, and sync to your organization when authenticated |
+
+## Deduplication
+
+Findings are deduplicated per project by identity. The same issue rediscovered on a later run updates the
+existing finding rather than creating a second one, so a long-lived issue doesn't inflate your counts and run
+history stays readable.
+
+Findings are anchored to a **symbol** rather than only a line number, so a finding survives edits that shift
+line numbers around it.
+
+## Closing the loop
+
+Two actions on a finding detail page turn a report into progress.
+
+### Accepting a fix
+
+When a finding has a generated patch, the suggested fix section can open a pull request with that patch
+applied. You review it like any other pull request.
+
+<Note>
+  Accepting a fix opens pull requests through the GitHub API, so it requires a GitHub-connected project.
+  Other providers can't do this yet, and the action is unavailable when a project has no code host connected.
+</Note>
+
+Patches aren't guesses. The agent that generated one edited the file, re-ran the detection to confirm the
+match was gone, and captured the resulting diff — for policy detections, an independent read-only verifier
+judged the result. You're reviewing a change that has already been checked, not a proposal.
+
+### Starting a chat
+
+**Start a chat** opens a session with the finding's context already loaded — the affected code, the agent's
+reasoning, and the generated patch if there is one. You type your question in the same step.
+
+Use it to ask the things a report can't anticipate: *is this actually reachable in production?*, *what else
+in this codebase has the same problem?*, *why is this the right fix?*
+
+The session is titled after the finding's file and line, so it's easy to find later.
+
+<Note>
+  This also requires a project connected to a code host — the agent needs to load the code to answer.
+</Note>
+
+## From finding to detection
+
+The highest-leverage move on a finding is turning it into a rule. A finding is one instance; a
+[detection](/harness/detections) catches the whole class from then on, in every repository, without an agent
+re-deriving it.
+
+Ask in chat, or add [`detection-author`](/harness/agent-library#detections) as a workflow step to do it
+automatically for every finding a scan produces.
+
+## Delivering findings automatically
+
+Findings don't have to be pulled — a workflow can push them where your team already works:
+
+- [Comment on the triggering pull request](/workflows/outputs#comment-on-triggering-pull-request), with links
+  back to the full finding.
+- [Gate merging](/workflows/outputs#gate-merging-on-security-review) until review passes or a human approves.
+
+## Next steps
+
+<CardGroup cols={2}>
+  <Card title="Turn findings into rules" icon="shield-check" href="/harness/detections">
+    Catch the class, not the instance.
+  </Card>
+
+  <Card title="Deliver them automatically" icon="arrow-right" href="/workflows/outputs">
+    Comments and merge gates.
+  </Card>
+</CardGroup>
diff --git a/context/overview.mdx b/context/overview.mdx
@@ -0,0 +1,71 @@
+---
+title: Context
+description: 'The harness is only as good as what it can see — repositories, and the security tools you already run.'
+---
+
+## Why context is its own layer
+
+An agent that can't see your environment is guessing. Console's agents don't answer from a static index
+or a model's memory of open-source code — they read your actual files, run commands against your actual
+repository, and query the findings your existing tools have already produced.
+
+That means the quality of everything downstream depends on what you've connected.
+
+## Two kinds of context
+
+| Kind | What it gives the agent | Set up in |
+| --- | --- | --- |
+| **[Projects](/context/projects)** | Your code. The repositories Console clones and reads. | Projects |
+| **[Connections](/context/connections)** | Your source control provider, and signal from the security and IT vendors you already run. | Connections |
+
+Projects are what an agent reads *from disk*. Connections are what it queries *over the network* —
+including the pull request events that let a workflow fire on its own.
+
+<Note>
+  These are prerequisites, not optional extras. Chat can't analyze a repository that isn't connected, and
+  a workflow has nothing to run against without at least one project.
+</Note>
+
+## Two ways to direct it
+
+Having context isn't the same as using it. Console gives you an interactive path and a declarative one:
+
+- **[Chat](/interactive/chat)** — point an agent at something and ask. Best when you don't yet know what
+  you're looking for, or when the question is a one-off.
+- **[Workflows](/workflows/overview)** — declare the repositories, the agent chain, and where results go,
+  then let it run unattended. Best when the task is worth repeating.
+
+The usual progression is to explore a question in chat, and once the approach works, promote it to a
+workflow.
+
+## What accumulates
+
+As agents work, results collect in your organization rather than evaporating with the conversation:
+
+- **[Findings](/context/findings)** — confirmed issues, each with the agent's reasoning, the affected
+  code, and often a suggested fix.
+- **[Detections](/harness/detections)** — the rules you've built up, which later runs apply
+  automatically.
+
+Both become context in their own right. A finding can seed a new chat; detections turn a one-time
+discovery into a permanent check.
+
+## Next steps
+
+<CardGroup cols={2}>
+  <Card title="Connect a repository" icon="folder-tree" href="/context/projects">
+    Give agents code to read.
+  </Card>
+
+  <Card title="Connect your vendors" icon="plug" href="/context/connections">
+    Source control, plus the security stack you already run.
+  </Card>
+
+  <Card title="What agents can read" icon="database" href="/context/vendor-data">
+    Exactly what a connection exposes today.
+  </Card>
+
+  <Card title="Findings" icon="magnifying-glass" href="/context/findings">
+    Where confirmed results land.
+  </Card>
+</CardGroup>