docs: glossary terminology + build hygiene cleanup (#46)

* Apply glossary terminology fixes

* Replace 'AI agent(s)' with 'agent(s)' across 15 guide pages — the
  glossary calls out the redundant AI prefix.
* Capitalize 'agent mode' to 'Agent Mode' in two guides and the
  privacy telemetry table.
* Replace 'whitelist' with 'allowlist' in the customize-appearance
  guide.

Note: 'blocklist' references in src/content/ were intentionally left
as-is. Most refer to Warp UI element names (e.g. 'Blocklist'
subshell feature, 'Hide secrets in blocklist' setting) or to the
list-of-Blocks UX, not security denylists. A separate content
rewrite pass would be needed to bring those into glossary alignment.

Co-Authored-By: Oz <oz-agent@warp.dev>

* Fix build noise and broken style_lint script

* astro.config.mjs: Map 'promql' to 'text' through Expressive Code's
  shiki.langAlias config. Shiki doesn't bundle a PromQL grammar, so
  every build emitted six 'language could not be found' warnings for
  the PromQL examples in monitoring.mdx. Aliasing keeps the semantic
  'promql' tag in the source MDX while silencing the warnings.

* .agents/skills/style_lint/style_lint.py: Update DOCS_ROOT from
  'docs' to 'src/content/docs' so the script actually scans Astro
  Starlight content. Previously '--all' silently scanned 0 files
  and reported 'No issues found'. Also include .mdx alongside .md
  in the file walk and fix a stale 'docs/' path in the changed-files
  and PR helpers.

Co-Authored-By: Oz <oz-agent@warp.dev>

* Restore "AI" in PM guide title for SEO

Per Rachael's review comment: keep "AI" in the title intentionally
for SEO even though our style guide treats "AI agents" as redundant.

Co-Authored-By: Oz <oz-agent@warp.dev>

---------

Co-authored-by: Oz <oz-agent@warp.dev>

Author: hongyi-chen

.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" />