docs: glossary terminology + build hygiene cleanup

.agents/skills/style_lint/style_lint.py

@@ -24,7 +24,11 @@
 # Configuration
 # ---------------------------------------------------------------------------
 
-DOCS_ROOT = Path("docs")
+# Astro Starlight content lives under src/content/docs/, not a top-level docs/.
+# This used to be `Path("docs")`, which silently scanned 0 files in the
+# Astro layout — running --all reported "No issues found" without auditing
+# anything.
+DOCS_ROOT = Path("src/content/docs")
 CHANGELOG_DIR = DOCS_ROOT / "changelog"
 EXCLUDED_DIRS = {"_book", "node_modules", ".docs"}
 
@@ -134,7 +138,7 @@ class Report:
 def find_all_md_files() -> List[Path]:
     """Find all markdown files in docs/, excluding build artifacts and changelog."""
     files = []
-    for f in DOCS_ROOT.rglob("*.md"):
+    for f in [*DOCS_ROOT.rglob("*.md"), *DOCS_ROOT.rglob("*.mdx")]:
         if any(part in EXCLUDED_DIRS for part in f.parts):
             continue
         # Exclude changelog (historical record)
@@ -148,12 +152,12 @@ def find_changed_md_files() -> List[Path]:
     """Find markdown files changed in the current branch vs main."""
     try:
         result = subprocess.run(
-            ["git", "diff", "--name-only", "origin/main...HEAD", "--", "docs/"],
+            ["git", "diff", "--name-only", "origin/main...HEAD", "--", str(DOCS_ROOT)],
             capture_output=True, text=True, check=True,
         )
         files = []
         for line in result.stdout.strip().split("\n"):
-            if line.endswith(".md") and os.path.exists(line):
+            if (line.endswith(".md") or line.endswith(".mdx")) and os.path.exists(line):
                 p = Path(line)
                 if not any(part in EXCLUDED_DIRS for part in p.parts):
                     files.append(p)
@@ -658,7 +662,7 @@ def create_pr_with_fixes() -> None:
     """Create a branch and PR with the auto-fixes."""
     branch = "fix/style-lint-auto-fixes"
     subprocess.run(["git", "checkout", "-b", branch], check=True)
-    subprocess.run(["git", "add", "docs/"], check=True)
+    subprocess.run(["git", "add", str(DOCS_ROOT)], check=True)
     result = subprocess.run(["git", "diff", "--cached", "--quiet"])
     if result.returncode == 0:
         print("No changes to commit.")

astro.config.mjs

@@ -67,6 +67,15 @@ export default defineConfig({
 				defaultProps: {
 					wrap: true,
 				},
+				// Map languages Shiki doesn't bundle to a safe fallback. PromQL
+				// blocks live in agent-platform/cloud-agents/self-hosting/monitoring.mdx;
+				// without this alias every build emits noisy "language could not be
+				// found" warnings while still falling back to plaintext.
+				shiki: {
+					langAlias: {
+						promql: 'text',
+					},
+				},
 			},
 			head: [
 				// SEO + PWA parity with the legacy GitBook docs. These were emitted

src/content/docs/guides/agent-workflows/how-to-explain-your-codebase-using-warp-rust-codebase.mdx

@@ -10,7 +10,7 @@ sidebar:
 import VideoEmbed from '@components/VideoEmbed.astro';
 import { Steps } from '@astrojs/starlight/components';
 
-Learn how to use Warp’s AI agent to explore and understand large, unfamiliar codebases — using semantic and symbol-level search.
+Learn how to use Warp’s agents to explore and understand large, unfamiliar codebases — using semantic and symbol-level search.
 
 <VideoEmbed url="https://www.youtube.com/watch?v=11rz9OYQ8Hg" />
 

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

@@ -16,7 +16,7 @@ Coding agents can produce hundreds of lines of code in seconds, but shipping tha
 
 ## Why review matters
 
-AI 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. 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.
 
 Common issues in AI-generated code:
 

src/content/docs/guides/build-an-app-in-warp/building-a-chrome-extension-d3js-javascript-html-css.mdx

@@ -10,7 +10,7 @@ import VideoEmbed from '@components/VideoEmbed.astro';
 import { Steps } from '@astrojs/starlight/components';
 
 :::tip
-This educational module teaches you step-by-step how to replicate the process shown in the video — building a **Sankey diagram Chrome extension** using **D3.js**, debugging, coordinating **multiple AI agents**, and deploying to the **Chrome Web Store**.
+This educational module teaches you step-by-step how to replicate the process shown in the video — building a **Sankey diagram Chrome extension** using **D3.js**, debugging, coordinating **multiple agents**, and deploying to the **Chrome Web Store**.
 :::
 
 <VideoEmbed url="https://youtu.be/xbvE_aoZ508?si=a3-4iKaSr8nn-esx" />
@@ -41,7 +41,7 @@ This educational module teaches you step-by-step how to replicate the process sh
 
    After fixing missing icons, the extension loads but initially shows only “Loading diagram.”\
    \
-   Debug this by taking a screenshot and feeding it to an AI agent for context by asking:
+   Debug this by taking a screenshot and feeding it to an agent for context by asking:
 
    ```
    It says loading diagram — why isn’t the chart appearing?

src/content/docs/guides/build-an-app-in-warp/building-a-slackbot.mdx

@@ -14,7 +14,7 @@ The setup takes just a few steps — clone, configure, and run — and requires
 
 ## Why this is useful
 
-* Run a self-hosted Slack bot that connects your team’s repos and Warp AI agents.
+* Run a self-hosted Slack bot that connects your team’s repos and Warp agents.
 * Provide your team with a coding assistant that can answer repo questions or help with PRs directly in Slack.
 
 ## Quickstart Setup
@@ -113,7 +113,7 @@ The setup takes just a few steps — clone, configure, and run — and requires
 * Authenticates to Slack (Socket Mode and Web API).
 * Authenticates to GitHub and clones the listed repos.
 * Starts listening for `app_mention` events and threaded messages.
-* Routes context and commands to Warp’s AI agent backend.
+* Routes context and commands to Warp’s agent backend.
 
 You can stop the bot anytime with `Ctrl + C` or run it persistently with:
 

src/content/docs/guides/configuration/how-to-set-coding-preferences-with-rules.mdx

@@ -13,7 +13,7 @@ Learn how to use Warp’s Rules feature to define your personal environment and
 
 <VideoEmbed url="https://youtu.be/zWvRB2zWr-4?si=tv-TIhsqEtLG9iDs" />
 
-This tutorial teaches you how to customize your development setup using **Warp’s Rules** — ensuring the AI agent always works in your preferred environment. Instead of constantly reminding it which package manager or environment to use, you can **store those preferences as persistent Rules** that apply automatically across projects.
+This tutorial teaches you how to customize your development setup using **Warp’s Rules** — ensuring agents always work in your preferred environment. Instead of constantly reminding them which package manager or environment to use, you can **store those preferences as persistent Rules** that apply automatically across projects.
 
 <Steps>
 

src/content/docs/guides/devops/how-to-prevent-secrets-from-leaking.mdx

@@ -13,7 +13,7 @@ Learn how to safeguard credentials and sensitive data using Warp’s secret-redu
 
 <VideoEmbed url="https://youtu.be/2ECPFKtQpVk?si=HHw14Tqj-QyHeByX" />
 
-This tutorial shows how to use Warp’s **Rules** to prevent AI agents or collaborators from exposing sensitive information while coding or sharing output. Whether you’re pair-programming, streaming, or reviewing code, Warp can automatically redact secrets before they’re ever seen by an agent.
+This tutorial shows how to use Warp’s **Rules** to prevent agents or collaborators from exposing sensitive information while coding or sharing output. Whether you’re pair-programming, streaming, or reviewing code, Warp can automatically redact secrets before they’re ever seen by an agent.
 
 <Steps>
 

src/content/docs/guides/devops/how-to-write-sql-commands-inside-a-postgres-repl.mdx

@@ -84,7 +84,7 @@ You’ll learn how to:
 
 4. #### Observe How Warp Learns from Context
 
-   As you continue issuing prompts, Warp’s AI agent **learns the structure of your database** by observing what’s printed in the REPL output.
+   As you continue issuing prompts, Warp’s agent **learns the structure of your database** by observing what’s printed in the REPL output.
 
    This means you can ask progressively more complex questions, and Warp will tailor the SQL accordingly.
 

src/content/docs/guides/external-tools/linear-mcp-retrieve-issue-data.mdx

@@ -6,7 +6,7 @@ description: >-
 ---
 import VideoEmbed from '@components/VideoEmbed.astro';
 
-Learn how to connect the Linear MCP server in Warp so your AI agent can access live data — like issues, tickets, and user assignments — directly from your Linear workspace.
+Learn how to connect the Linear MCP server in Warp so your agents can access live data — like issues, tickets, and user assignments — directly from your Linear workspace.
 
 <VideoEmbed url="https://youtu.be/jxeMfuS1pXk" />
 

src/content/docs/guides/external-tools/puppeteer-mcp-scraping-amazon-web-reviews.mdx

@@ -65,7 +65,7 @@ You’ll learn how to:
    * `puppeteer.screenshot`
    * `puppeteer.evaluate`
 
-   These represent actions Warp can call automatically through its AI agent.
+   These represent actions Warp can call automatically through its agents.
 
 2. #### Use Voice Input to Trigger Automation
 

src/content/docs/guides/external-tools/sentry-mcp-fix-sentry-error-in-empower-website.mdx

@@ -17,7 +17,7 @@ This tutorial is based solely on the provided transcript. It teaches how to use
 
 ### Overview
 
-The **Sentry MCP server** gives Warp’s AI agents access to authenticated Sentry error data.\
+The **Sentry MCP server** gives Warp’s agents access to authenticated Sentry error data.\
 This enables detailed diagnostics and automated fixes that would otherwise be impossible using AI alone.
 
 You’ll learn how to:
@@ -82,7 +82,7 @@ You’ll learn how to:
 
 4. #### Diagnose the Error Using Warp
 
-   Back in Warp, prompt the AI agent to fetch and analyze the issue:
+   Back in Warp, prompt the agent to fetch and analyze the issue:
 
    ```
    Diagnose this Sentry error and show where it’s coming from in my code.

src/content/docs/guides/frontend/how-to-replace-a-ui-element-in-warp-rust-codebase.mdx

@@ -28,9 +28,9 @@ This demo showcases Warp’s ability to safely make intelligent code changes wit
    ```
    Please create a new branch for me according to the format in the attached Linear URL.
 
-   I’ve attached screenshots of what the agent mode and sparkle icons look like.
+   I’ve attached screenshots of what the Agent Mode and sparkle icons look like.
    I would like you to understand those icons, search for their use in the code,
-   and wherever we’re using sparkles, replace them with the agent mode icon.
+   and wherever we’re using sparkles, replace them with the Agent Mode icon.
    Specifically, make sure this happens in the history menu.
    Please give me a plan before making any coding changes.
    ```

src/content/docs/guides/getting-started/how-to-customize-warps-appearance.mdx

@@ -50,7 +50,7 @@ Open **Settings → AI** to control:
   * Running commands
   * Planning tasks
 
-You can also whitelist or block specific commands that always require confirmation.
+You can also allowlist or block specific commands that always require confirmation.
 
 ---
 

src/content/docs/guides/getting-started/welcome-to-warp.mdx

@@ -12,7 +12,7 @@ import VideoEmbed from '@components/VideoEmbed.astro';
 
 When you open Warp, you’ll see something familiar — a command line interface — but it’s much more than a traditional terminal.\
 \
-Warp is an Agentic Development Environment (ADE), meaning it’s a space where your primary mode of interaction is through prompts to an AI agent.
+Warp is an Agentic Development Environment (ADE), meaning it’s a space where your primary mode of interaction is through prompts to an agent.
 
 You can still use Warp just like any terminal:
 

src/content/docs/support-and-community/privacy-and-security/privacy.mdx

@@ -142,7 +142,7 @@ If you're a [Team](/knowledge-and-collaboration/teams/) admin, the deletion flow
 | `AgentMode.Code.SuggestedEditAcceptClicked` | User selected Accept for a code diff suggestion in Agent Mode |
 | `AgentMode.Code.SuggestedEditReceived` | Agent Mode suggested a code edit |
 | `AgentMode.Code.SuggestedEditResolved` | Agent Mode pending code edit suggestion resolved |
-| `AgentMode.CreatedAIBlock` | Created an AI block in agent mode |
+| `AgentMode.CreatedAIBlock` | Created an AI block in Agent Mode |
 | `AgentMode.Error` | Received an error when getting Agent Mode response |
 | `AgentMode.ExecutedWarpDrivePrompt` | Executed a saved prompt. |
 | `AgentMode.ExitedShellProcess` | An agent-requested command caused the shell process to exit |
@@ -151,13 +151,13 @@ If you're a [Team](/knowledge-and-collaboration/teams/) admin, the deletion flow
 | `AgentMode.Grep.Failed` | The grep tool failed to complete |
 | `AgentMode.Grep.Succeeded` | The grep tool completed successfully |
 | `AgentMode.NaturalLanguageDetection.InputBufferSubmitted` | Input buffer submitted |
-| `AgentMode.OpenedCitation` | Opened a citation that was surfaced in agent mode |
+| `AgentMode.OpenedCitation` | Opened a citation that was surfaced in Agent Mode |
 | `AgentMode.Orchestration.TeamAgentCommunicationFailed` | Failed to send an orchestration message or lifecycle event for a TeamAgent |
 | `AgentMode.PotentialAutoDetectionFalsePositive` | Manually toggled input to shell mode after input was auto-detected as natural language. |
 | `AgentMode.QueryAttemptAtLImit` | Tried to send an Agent Mode query but they already reached the query limit |
 | `AgentMode.RequestRetrySucceeded` | Agent Mode request succeeded after retrying following an initial error |
 | `AgentMode.SetupCreateEnvironmentAction` | User clicked a button in the Agent Mode setup create environment step |
-| `AgentMode.SurfacedCitations` | Agent mode used and cited external sources that were used in its response |
+| `AgentMode.SurfacedCitations` | Agent Mode used and cited external sources that were used in its response |
 | `AgentMode.ToggleAutoDetectionSetting` | Toggled the setting that enables or disables natural language auto-detection in the input.  |
 | `AgentNotification.Shown` | An agent notification was shown to the user (toast or mailbox) |
 | `AgentTip Clicked` | User clicked a link or action in an Agent Tip |