docs: polish agent workflow guides

src/content/docs/guides/agent-workflows/build-a-triage-agent.mdx

@@ -17,7 +17,7 @@ Learn how to use the {VARS.WARP_AUTOMATION_PLATFORM} to build a triage agent tha
 
 * A Warp account ([sign up at warp.dev](https://www.warp.dev))
 * A GitHub repository with Issues enabled
-* A cloud environment with access to your repository ([create one](/platform/environments/#create-an-environment-with-guided-setup-in-warp))
+* A cloud environment with access to your repository ([create one](/platform/environments/configuring-environments/#create-an-environment-with-guided-setup))
 * A Warp API key added to your CI secrets as `WARP_API_KEY` ([create one](/reference/cli/api-keys/#from-the-web-app-recommended))
 
 ## 1. Define your triage criteria

src/content/docs/guides/agent-workflows/how-to-review-ai-generated-code.mdx

@@ -1,8 +1,8 @@
 ---
 title: Review AI-generated code
 description: >-
-  Review AI-generated code in Warp with visual diffs and inline comments —
-  works with Claude Code, Codex, or any CLI agent.
+  Review AI-generated code in Warp with visual diffs and inline comments.
+  Use this workflow with Claude Code, Codex, or any CLI agent.
 sidebar:
   label: "Review AI-generated code"
 featured: true
@@ -12,44 +12,44 @@ tags:
 
 ---
 
-Coding agents can produce hundreds of lines of code in seconds, but shipping that code without review is risky. This guide provides a practical workflow for reviewing agent-generated code in Warp, catching common issues, and giving structured feedback that the agent can act on. Plan on about 10 minutes to complete.
+Coding agents can produce hundreds of lines of code in seconds, but shipping that code without review is risky. In Warp, you can use visual diffs and inline comments to catch common issues and give the agent structured feedback it can act on. Plan on about 10 minutes to complete.
 
 ## Prerequisites
 
-* **A Git-tracked project** — Code review in Warp works on any Git repository.
-* **An AI coding agent** — This workflow applies to any CLI agent: [Claude Code](/guides/external-tools/how-to-set-up-claude-code/), [Codex](/guides/external-tools/how-to-set-up-codex-cli/), OpenCode, or Warp's built-in agent. See [Third-party CLI agents](/agents/cli-agents/overview/) for setup.
+* **A Git-tracked project** - Code Review in Warp works with any Git repository.
+* **A coding agent** - Use the Warp Agent or a supported third-party CLI agent: [Claude Code](/guides/external-tools/how-to-set-up-claude-code/), [Codex](/guides/external-tools/how-to-set-up-codex-cli/), [Gemini CLI](/guides/external-tools/how-to-set-up-gemini-cli/), or [OpenCode](/guides/external-tools/how-to-set-up-opencode/). See [Third-party CLI agents](/agents/cli-agents/overview/) for the full list.
 
 ## Why review matters
 
-Agents are fast but imperfect. They hallucinate imports, introduce subtle logic errors, make bad architectural decisions, and duplicate code. Reviewing agent output is the step that turns agentic development from vibe coding into a workflow you can trust.
+Agents are fast but imperfect. An agent can hallucinate imports, introduce subtle logic errors, make poor architectural decisions, or duplicate code. Reviewing agent output turns agent-assisted development into a workflow you can trust.
 
-Common issues in AI-generated code:
+Review AI-generated code for the following issues.
 
-* **Hallucinated imports** — referencing packages or modules that don't exist in your project
-* **Redundant logic** — duplicating existing functionality instead of reusing it
-* **Questionable architectural decisions** — adding new patterns instead of following existing ones, or restructuring code in ways that conflict with your project's architecture
-* **Security gaps** — hardcoded credentials, missing input validation, or overly permissive permissions
-* **Style drift** — ignoring your project's conventions for naming, error handling, or file structure
-* **Incomplete error handling** — happy-path code that crashes on edge cases
+* **Hallucinated imports** - Referencing packages or modules that don't exist in your project.
+* **Redundant logic** - Duplicating existing functionality instead of reusing it.
+* **Questionable architectural decisions** - Adding new patterns instead of following existing ones, or restructuring code in ways that conflict with your project's architecture.
+* **Security gaps** - Hardcoding credentials, omitting input validation, or using overly broad access controls.
+* **Style drift** - Ignoring your project's conventions for naming, error handling, or file structure.
+* **Incomplete error handling** - Writing happy-path code that crashes on edge cases.
 
 ## 1. Give the agent a task
 
-Whether you're using Claude Code, Codex, or Warp's built-in agent, start by giving your agent a task. For example:
+Start by giving the agent a task. Try the following prompt:
 
-```
+```text
 Fix the authentication middleware to handle expired tokens gracefully
 ```
 
 The agent will modify one or more files.
 
 ## 2. Open the Code Review panel
 
-Once the agent has finished the task, open Warp's [Code Review panel](/code/code-review/) to see every file that changed. You can open it in several ways:
+Once the agent has finished the task, open Warp's [Code Review panel](/code/code-review/) to see every file that changed. Open the panel in any of the following ways:
 
-* **Keyboard shortcut**: `⌘+Shift++` (macOS) or `Ctrl+Shift++` (Windows/Linux)
-* **Git diff chip**: Click the diff chip in the terminal input that shows files modified and lines changed
-* **Review changes button**: After an agent conversation, click **Review changes** at the bottom of the conversation
-* **Tab bar**: Click the Code Review button in the top-right corner of Warp
+* **Keyboard shortcut** - Press `⌘+Shift++` (macOS) or `Ctrl+Shift++` (Windows/Linux).
+* **Git diff chip** - Click the diff chip in the terminal input that shows files modified and lines changed.
+* **Review changes button** - After an agent conversation, click **Review changes** at the bottom of the conversation.
+* **Tab bar** - Click the Code Review button in the top-right corner.
 
 <figure style={{ maxWidth: "350px" }}>
 ![Code Review button in the top-right corner of the Warp title bar showing file and line change counts](../../../../assets/guides/code-review-button.png)
@@ -65,13 +65,13 @@ The panel shows all uncommitted changes as a visual diff, grouped by file. Addit
 
 ## 3. Review diffs by file
 
-With the Code Review panel, you can review changes file-by-file:
+Use the Code Review panel to inspect each changed file, compare changes against a base branch, and edit the diff when needed:
 
-* **Browse all changed files** using the file sidebar.
-* **Switch diff views** to compare against uncommitted changes or against `main`/`master` to see the full scope of what would land in a PR.
-* **Click anywhere in the code** to edit diffs directly in the panel.
+* **Browse all changed files** - Use the file sidebar.
+* **Choose a comparison view** - Use the comparison menu to inspect uncommitted changes, compare against the detected `main` or `master` branch, or choose another branch.
+* **Edit a diff** - Click anywhere in the code to edit directly in the panel.
 
-Focus on the areas where agents are most likely to make mistakes: imports, error handling, and anything that touches security or authentication.
+Pay particular attention to imports, error handling, and code that touches security or authentication.
 
 <figure style={{ maxWidth: "375px" }}>
 ![Code Review panel with file navigation sidebar showing changed files](../../../../assets/guides/code-review-file-sidebar.png)
@@ -80,8 +80,8 @@ Focus on the areas where agents are most likely to make mistakes: imports, error
 
 ## 4. Leave inline comments on issues
 
-Click the "Add comment" button on any line or block of code and add a comment describing what needs to change. Warp anchors each comment to the exact file and line, so any agent understands precisely what to fix.
-You can add as many comments as you need before submitting — Warp batches them so the agent receives all your feedback at once instead of processing changes one at a time.
+Click **Add comment** on any line or block of code, then describe the change. Warp anchors each comment to the exact file and line, so the agent knows precisely what to fix.
+Add as many comments as you need before you submit. Warp sends the complete batch at once, rather than asking the agent to process changes one at a time.
 
 <figure style={{ maxWidth: "563px" }}>
 ![Adding an inline comment on a diff line in the Code Review panel](../../../../assets/guides/code-review-inline-comment.png)
@@ -90,17 +90,17 @@ You can add as many comments as you need before submitting — Warp batches them
 
 ## 5. Submit all comments to the agent
 
-Once you've reviewed each file and left comments, submit the complete batch. The agent receives all your feedback, applies the requested changes in one pass, and returns an updated diff.
+Once you've reviewed each file and left comments, submit the complete batch. The agent applies the requested changes in one pass and returns an updated diff.
 
-Review the updated diff to verify the fixes. Repeat this cycle until the code meets your standards: comment, submit, review.
+Review the updated diff to verify the fixes. Repeat the cycle until the code meets your standards: comment, submit, then review.
 
 :::note
-This workflow applies to **any CLI agent** running in Warp, not just the built-in agent. You can leave inline comments on diffs generated by Claude Code, Codex, or OpenCode and send them back to the running agent session.
+This workflow applies to any running CLI agent session in Warp. You can leave inline comments on a diff and send them back to the agent session.
 :::
 
 ## 6. Run your project's checks before committing
 
-Before accepting the changes, run your project's test suite, linter, and type checker. Agent-generated code might pass a visual review but fail automated checks.
+Before accepting the changes, run your project's test suite, linter, and type checker. Agent-generated code can pass a visual review and still fail automated checks.
 
 ```bash
 # Example: run tests and lint
@@ -109,27 +109,30 @@ npm test && npm run lint
 
 If checks fail, you can either fix the issues manually in the Code Review panel or send the error output back to the agent as context for another iteration.
 
-:::note
-**Quick review checklist**: When reviewing agent-generated changes, check that imports resolve, new code doesn't duplicate existing functionality, credentials aren't hardcoded, error handling covers failure cases, style matches your project, tests still pass, and the agent only changed what was asked.
-:::
+### Quick review checklist
+
+* [ ] Imports resolve.
+* [ ] New code doesn't duplicate existing functionality.
+* [ ] Credentials aren't hardcoded.
+* [ ] Error handling covers failure cases.
+* [ ] Style matches your project.
+* [ ] Tests pass.
+* [ ] The agent changed only what you asked.
 
 ## Productivity tips
 
-* **Attach diffs as context** — Select a diff hunk in the Code Review panel and attach it to your next prompt. This grounds the agent's response in your actual code changes. See [Selection as context](/agents/local-agents/agent-context/selection-as-context/) for details.
-* **Revert individual hunks** — Don't like one specific change? Revert just that hunk from the Code Review panel without undoing the rest of the agent's work.
-* **Compare against main** — Switch the diff view to "Changes vs. main" to see how the agent's work fits into the full scope of your branch, not just the latest edits.
-* **Use rules to prevent recurring issues** — If you notice the agent repeatedly making the same mistake (wrong import paths, incorrect naming conventions), add a [Rule](/agents/capabilities/rules/) so it learns your project's standards.
+* **Attach diffs as context** - Select a diff hunk in the Code Review panel and attach it to your next prompt. This grounds the agent's response in your actual code changes. See [Selection as context](/agents/local-agents/agent-context/selection-as-context/) for details.
+* **Revert individual hunks** - Revert one change from the Code Review panel without undoing the rest of the agent's work.
+* **Compare against main** - Switch the diff view to "Changes vs. main" to see how the agent's work fits into the full scope of your branch, not just the latest edits.
+* **Use Rules to prevent recurring issues** - If the agent repeatedly makes the same mistake, such as using incorrect import paths or naming conventions, add a [Rule](/agents/capabilities/rules/) with your project's standards.
 
 ## Next steps
 
-You now have a structured workflow for reviewing AI-generated code in Warp: visual diff review, inline comments that feed back to the agent, and batch feedback submission. This workflow works with any CLI coding agent: Claude Code, Codex, OpenCode, or Warp's built-in agent.
+You now have a structured workflow for reviewing AI-generated code in Warp. It combines visual diff review, inline comments, and batch feedback.
 
 Explore related guides and features:
 
-* [Set up Claude Code](/guides/external-tools/how-to-set-up-claude-code/) or [Set up Codex CLI](/guides/external-tools/how-to-set-up-codex-cli/) to start using third-party agents in Warp
-* [Attach agent session context to GitHub PRs](/guides/agent-workflows/how-to-attach-agent-session-context-to-github-prs/) to give reviewers the prompt, plan, commands, logs, and validation behind agent-generated changes
-* [Run multiple agents at once](/guides/agent-workflows/how-to-run-multiple-ai-coding-agents/) to compare outputs from different agents on the same task
-* [Claude Code in Warp](https://www.warp.dev/agents/claude-code) | [Codex in Warp](https://www.warp.dev/agents/codex) | [Gemini CLI in Warp](https://www.warp.dev/agents/gemini-cli) | [OpenCode in Warp](https://www.warp.dev/agents/opencode) — agent-specific overviews on the Warp marketing site
-* [Code Review panel](/code/code-review/) — full reference for all Code Review features
-* [Interactive Code Review](/agents/local-agents/interactive-code-review/) — detailed docs on inline comments and batch feedback
-* [Third-party CLI agents](/agents/cli-agents/overview/) — all supported agents and Warp's universal agent features
+* [Attach agent session context to GitHub PRs](/guides/agent-workflows/how-to-attach-agent-session-context-to-github-prs/) to give reviewers the full context behind agent-generated changes.
+* [Run multiple agents at once](/guides/agent-workflows/how-to-run-multiple-ai-coding-agents/) to compare their outputs on the same task.
+* [Code Review panel](/code/code-review/) for a full reference to Code Review features.
+* [Interactive Code Review](/agents/local-agents/interactive-code-review/) for detailed instructions on inline comments and batch feedback.