Restructure Console docs into agents, data, and workflows

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 |
+| `Agents & detections` (`agents/`) | The authorable primitives — agents, skills, detections — and the tool surface |
+| `Data & connections` (`data/`) | 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 — `/agents/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`.

agents/detections.mdx

@@ -0,0 +1,126 @@
+---
+title: Detections
+description: 'Reusable rules that outlive any one conversation — OpenGrep patterns and natural-language policies.'
+---
+
+## Why detections exist
+
+A finding describes one moment: this file, this commit, this vulnerability. A **detection** is the rule
+behind it, and it keeps checking forever.
+
+This is the difference between an agent that's useful once and a platform that compounds. When an agent
+confirms a vulnerability, the valuable output isn't only the fix — it's the rule that catches the same
+mistake in every repository from then on, cheaply, without an agent having to re-derive it.
+
+## Detection types
+
+| Type | Format | What it's good at |
+| --- | --- | --- |
+| **OpenGrep rule** | YAML | Structural patterns with a known shape — a dangerous API, a missing flag, a taint path from source to sink. Fast and deterministic. |
+| **Policy** | Natural language | Intent that resists pattern matching — "every endpoint that mutates data must check authorization", "no service may log request bodies". Evaluated by an agent. |
+| **CodeQL query** | QL | Deep dataflow queries. See the limitation below. |
+
+<Warning>
+  **CodeQL detections can be authored but are not yet executed.** Only OpenGrep and policy detections have
+  runtimes today; `detections-runner` stores other types and skips them with a note. The
+  `codeql-rule-creator` skill and the editor's CodeQL support exist so the rules are ready when execution
+  lands.
+</Warning>
+
+### OpenGrep rules
+
+OpenGrep rules support two modes:
+
+- **`search`** — match a pattern. Use `pattern`, `patterns`, `pattern-either`, or `pattern-regex`.
+- **`taint`** — track data flow. Declare `pattern-sources`, `pattern-sinks`, and optionally
+  `pattern-sanitizers`; a match is a source reaching a sink with nothing neutralizing it in between.
+
+Taint mode is the one that earns its keep for security work, because it encodes *reachability* rather than
+mere presence.
+
+Rules carry a severity of `INFO`, `WARNING`, or `ERROR`, and OpenGrep filters by the rule's own `languages`
+field at run time — so an irrelevant rule exits cheaply rather than wasting a pass.
+
+### Policy detections
+
+A policy is a security requirement written in plain language. At run time, `detections-runner` spawns a
+`policy-evaluator` per policy, bound to that detection so every finding links back to it.
+
+Policies are the right tool when the rule is about intent — business logic, authorization, data handling —
+where no pattern captures the requirement and a human reviewer would need to reason about the code.
+
+## Fields that matter
+
+| Field | Values | What it does |
+| --- | --- | --- |
+| **Status** | `TEST`, `PRODUCTION` | Whether the detection is still being evaluated or is trusted. Promote once its results hold up. |
+| **Severity** | `critical`, `high`, `medium`, `low` | How serious a match is. |
+| **Disposition** | `flag`, `escalate` | What should happen on a match — record it, or escalate it. |
+| **Tags** | free-form | Grouping and filtering. |
+| **Project** | optional | Scopes the detection to one repository. Unset means it applies organization-wide. |
+
+### The test-to-production lifecycle
+
+New detections start at `TEST`. Run them, review what they catch, tune the rule, and promote to
+`PRODUCTION` when the signal is trustworthy.
+
+This exists because a noisy detection is worse than no detection — it trains your team to ignore results.
+Keeping unproven rules visibly in `TEST` lets you build the library without eroding trust in it.
+
+## Where detections come from
+
+| Source | Meaning |
+| --- | --- |
+| `manual` | Authored by a person, or by an agent on request. |
+| `risk-register` | Compiled from your organization's risk register. |
+| `threat-model` | Compiled from a threat model. |
+
+Compiled detections keep provenance back to the upstream document, so a rule can be traced to the
+requirement that motivated it.
+
+## Authoring a detection
+
+**In the web console.** Open **Detections** and create one. The editor syntax-highlights by type — YAML for
+policies, Markdown with YAML frontmatter for rule types — and labels the language in the header. Customer
+types the UI doesn't recognize still render with a generic label rather than breaking.
+
+**With an agent.** Often the better path, because agents can validate as they go:
+
+- `opengrep-rule-creator` writes and checks an OpenGrep rule.
+- `policy-detection-creator` turns a requirement into a stored policy.
+- `detection-author` reads a scan's findings and authors a detection for each — the automated version of
+  the same loop.
+
+Ask in [chat](/interactive/chat): *"Write an OpenGrep rule that catches this pattern and store it as a test
+detection."*
+
+## Running detections
+
+Add [`detections-runner`](/agents/library#detections) as a workflow step. It lists every stored
+detection, triages which apply, and dispatches by type — OpenGrep rules directly, policies via one child
+evaluator each. Findings link back to the detection that produced them, so you can see which rules are
+earning their place.
+
+Its bias is deliberate: it dispatches when in doubt, because a detection that never ran is worse than a
+wasted pass.
+
+## The compounding loop
+
+1. An agent confirms a vulnerability in [chat](/interactive/chat) or a workflow run.
+2. `detection-author` — or you — turns it into a detection, at `TEST`.
+3. You review what it catches and promote it to `PRODUCTION`.
+4. A `detections-runner` workflow applies it on every pull request from then on.
+
+Step 4 is cheap and repeatable. That's the payoff for the reasoning spent in step 1.
+
+## Next steps
+
+<CardGroup cols={2}>
+  <Card title="Run them in a workflow" icon="workflow" href="/workflows/create-a-workflow">
+    Add `detections-runner` to a chain.
+  </Card>
+
+  <Card title="Findings" icon="magnifying-glass" href="/data/findings">
+    What a detection produces when it matches.
+  </Card>
+</CardGroup>

agents/how-agents-work.mdx

@@ -0,0 +1,91 @@
+---
+title: How agents work
+description: 'What an agent is, how it runs, and how agents delegate to each other.'
+---
+
+## What an agent is
+
+An agent is a participant in the harness: a model, a set of tools it may call, a budget, and a body of
+instructions. Give it a task and it works until the task is done or the budget runs out.
+
+Unlike a scanner, an agent decides what to do next based on what it just learned. It reads a file, notices a
+suspicious call, traces the caller, runs a command to check a hypothesis, and either confirms or discards it.
+That loop — reason, act, observe, reason again — is what makes agents suited to security work, where the
+interesting questions are about *whether* something is reachable rather than *whether* a pattern appears.
+
+## How a run proceeds
+
+1. **The agent receives a task.** In chat that's your message; in a workflow it's a briefing composed by the
+   orchestrator.
+2. **It reasons and calls tools.** Each call returns a result it reads before deciding the next step.
+3. **It may load a skill** with `activate_skill` when it hits a task a documented procedure covers.
+4. **It may delegate** with `spawn_agent`, handing focused work to a child and waiting for the summary.
+5. **It records durable results** — findings, patches, detections — rather than only replying in prose.
+6. **It stops** when the task is done, the budget is exhausted, or it's cancelled.
+
+Everything an agent does in step 2 is bounded by the [tool surface](/agents/tool-reference).
+
+## Budgets
+
+Two ceilings keep a run from going forever, both settable per agent:
+
+- **`maxIterations`** — how many reasoning↔tool cycles it may take.
+- **`timeout`** — wall-clock milliseconds for the whole execution.
+
+For an orchestrator, `timeout` covers every child it spawns, so it must exceed the worst-case sum of their
+durations. Leave both unset unless the agent is genuinely an outlier.
+
+## Delegation and agent trees
+
+An agent can spawn sub-agents, and those can spawn their own, forming a tree. This exists for two reasons:
+
+- **Focus.** A child starts with a clean context scoped to one job, so a broad scan doesn't drown in detail
+  from the first file it opened.
+- **Parallelism.** Independent work runs concurrently — one evaluator per detection, one patch generator per
+  file.
+
+A child returns a **summary**, not its full transcript. The parent sees the conclusion and quotes it forward.
+This is why an agent's `description` and its final summary both matter so much: they're the interface
+between agents.
+
+You can watch the tree live — as a nested view in the CLI, and in the web console's chat while a turn runs.
+
+### Forcing sequential delegation
+
+Set [`sequential-spawns: true`](/agents/writing-an-agent#sequential-spawns) when steps depend on each other
+and the agent must see one result before starting the next. Console's `workflow-runner` uses exactly this to
+guarantee workflow steps run in order.
+
+## Where agents come from
+
+| Source | Description |
+| --- | --- |
+| **Platform agents** | The library Console ships. See [the agent library](/agents/library). |
+| **Organization agents** | Agents your team writes, in the web console or the CLI. |
+
+Both appear together wherever agents are listed, and the workflow orchestrator treats them identically. An
+organization agent whose `name` matches a platform agent **shadows** it — the supported way to customize
+built-in behavior.
+
+## When to write your own
+
+Reach for a new agent when:
+
+- The task is a distinct job with its own output — "audit dependencies", "review IaC for public exposure".
+- You want different tool permissions, like a read-only reviewer that can't modify code.
+- You want a different model for cost or depth reasons.
+
+Prefer a [skill](/agents/skills) instead when you're capturing *how to do one thing well* and an existing
+agent could follow it. Skills are cheaper: no separate budget, no separate model, loaded only when relevant.
+
+## Next steps
+
+<CardGroup cols={2}>
+  <Card title="Write an agent" icon="file-code" href="/agents/writing-an-agent">
+    The frontmatter reference.
+  </Card>
+
+  <Card title="Chain them" icon="workflow" href="/workflows/agent-chain">
+    Sequence agents into a workflow.
+  </Card>
+</CardGroup>

agents/library.mdx

@@ -0,0 +1,87 @@
+---
+title: The agent library
+description: 'The agents Console ships, what each is for, and which ones to put in a workflow.'
+---
+
+## Using the library
+
+Console ships the agents below. They appear in the agent list and the
+[workflow agent picker](/workflows/create-a-workflow#agents) alongside anything your organization writes.
+
+They're also the best available examples of the format — if you're about to
+[write an agent](/agents/writing-an-agent), open one first and read how its frontmatter and instructions
+are put together.
+
+## Scanning
+
+The vulnerability scanners share one approach: map the repository's security conventions, hunt for places
+the implementation diverges from that intent, then confirm candidates through analysis. They differ only in
+how broadly they hunt and how deeply they confirm.
+
+| Agent | Profile | Use when |
+| --- | --- | --- |
+| `vulnerability-scanner-basic` | Pursues the top 6 candidates, caps at 6 findings, generic analysis only. | You want a fast signal — a pull request check where latency matters. |
+| `vulnerability-scanner-standard` | Pursues the top 10 candidates, caps at 10 findings, uses the class-specific skill library plus confirmation. | The default choice for most workflows. |
+| `vulnerability-scanner-comprehensive` | Pursues the top 40 candidates, caps at 40 findings, uses the full skill library and a more capable model. | Auditing a repository in depth, where thoroughness matters more than speed. |
+
+The caps are deliberate. A scanner that returns everything it half-suspects is noise; these stop at a
+defined budget so the results stay reviewable.
+
+## Detections
+
+| Agent | What it does |
+| --- | --- |
+| `detections-runner` | Runs every [detection](/agents/detections) stored in your organization against the repository, dispatching by type — OpenGrep rules directly, policy detections via one child evaluator each. Findings are linked to the detection that produced them. |
+| `detection-author` | Reads findings from an earlier step and authors a reusable detection for each, choosing between an OpenGrep rule and a natural-language policy. |
+
+These two are the ends of a loop worth understanding: `detection-author` turns a one-time discovery into a
+permanent rule, and `detections-runner` is what applies every rule you've accumulated from then on.
+
+## Review
+
+| Agent | What it does |
+| --- | --- |
+| `code-reviewer` | Reviews code for security vulnerabilities, performance issues, and best practices. |
+| `security-analyzer` | Deep security analysis with taint tracking and vulnerability assessment. |
+
+## Agents spawned by other agents
+
+These exist in the library but are normally driven by another agent rather than added directly as workflow
+steps:
+
+| Agent | Spawned by | Role |
+| --- | --- | --- |
+| `patch-generator` | `detections-runner`, when patch generation is enabled | Generates a verified patch for one detection's findings in one file: edits the file, re-runs the detection to confirm the fix, captures the diff, and records it. |
+| `policy-evaluator` | `detections-runner` | Evaluates one policy detection against the repository, bound to that detection so every finding links back to it. |
+| `policy-fix-verifier` | `patch-generator` | Independently judges whether a patched file still violates a policy. Deliberately read-only — it returns a verdict and cannot report findings or edit code. |
+
+You *can* name one as a workflow step, but they expect a briefing their usual parent provides, so they work
+best left to it.
+
+## The orchestrator
+
+`workflow-runner` is the agent that executes workflows: it reads a workflow's description and steps, spawns
+each step's agent in order, and composes each briefing. You don't add it to a chain — it *is* the chain. See
+[the agent chain](/workflows/agent-chain) for how it composes briefings.
+
+## Common chains
+
+| Goal | Chain |
+| --- | --- |
+| Fast pull request check | `vulnerability-scanner-basic` |
+| Standard pull request review | `vulnerability-scanner-standard` |
+| Turn findings into permanent rules | `vulnerability-scanner-standard` → `detection-author` |
+| Apply everything you've already vetted | `detections-runner` |
+| Deep audit | `vulnerability-scanner-comprehensive` → `security-analyzer` |
+
+## Next steps
+
+<CardGroup cols={2}>
+  <Card title="Write your own" icon="file-code" href="/agents/writing-an-agent">
+    Extend or shadow any of these.
+  </Card>
+
+  <Card title="Build a workflow" icon="workflow" href="/workflows/create-a-workflow">
+    Put a chain to work.
+  </Card>
+</CardGroup>