From bba533504fba95bdf2ccb25f0f66ea5d6bacfaac Mon Sep 17 00:00:00 2001 From: "warp-factories[bot]" <243557089+warp-factories[bot]@users.noreply.github.com> Date: Fri, 21 Aug 2026 07:02:09 +0000 Subject: [PATCH 1/3] Automated SEO fixes: trim long descriptions and expand Factory MCP title Co-Authored-By: Oz --- src/content/docs/factories/factory-mcp.mdx | 4 +++- src/content/docs/platform/harnesses/authentication.mdx | 4 ++-- src/content/docs/platform/harnesses/warp-agent.mdx | 4 ++-- src/content/docs/platform/self-hosting/index.mdx | 5 ++--- src/content/docs/platform/self-hosting/monitoring.mdx | 5 ++--- 5 files changed, 11 insertions(+), 11 deletions(-) diff --git a/src/content/docs/factories/factory-mcp.mdx b/src/content/docs/factories/factory-mcp.mdx index 66598499..353887fa 100644 --- a/src/content/docs/factories/factory-mcp.mdx +++ b/src/content/docs/factories/factory-mcp.mdx @@ -1,5 +1,5 @@ --- -title: Factory MCP +title: Factory MCP for Warp Factories description: >- Connect any coding agent to your team's factories to send in work, continue tasks locally, and hand results back. @@ -7,6 +7,8 @@ sidebar: label: "Factory MCP" --- +# Factory MCP for Warp Factories + Factory MCP is a hosted Model Context Protocol (MCP) server that connects coding agents to your team's factories, in both directions: the agent you already work with — in Warp or in any MCP-capable tool — can send work to a factory, or take work over from one by pulling a task down, continuing it locally, and handing the result back. The factory keeps a single record of each task throughout. Whether a change happens in the cloud or on your machine, it lands on the same task with the same history and conversation. A task is the factory's work item: the same unit of work that appears in the factory dashboard's [Activity view](/factories/factory-dashboard/#track-work-items-on-activity). diff --git a/src/content/docs/platform/harnesses/authentication.mdx b/src/content/docs/platform/harnesses/authentication.mdx index 26136813..3b9fc741 100644 --- a/src/content/docs/platform/harnesses/authentication.mdx +++ b/src/content/docs/platform/harnesses/authentication.mdx @@ -1,8 +1,8 @@ --- title: Third-party cloud agent authentication description: >- - Connect your Anthropic or OpenAI credentials to the {{WARP_AUTOMATION_PLATFORM}}, then launch Claude Code - or Codex as cloud agents from the desktop app, {{WEB_APP}}, or API. + Connect Anthropic or OpenAI credentials to the {{WARP_AUTOMATION_PLATFORM}} to + run Claude Code or Codex as cloud agents. sidebar: label: "Authentication" --- diff --git a/src/content/docs/platform/harnesses/warp-agent.mdx b/src/content/docs/platform/harnesses/warp-agent.mdx index 53d2338f..c5d112cc 100644 --- a/src/content/docs/platform/harnesses/warp-agent.mdx +++ b/src/content/docs/platform/harnesses/warp-agent.mdx @@ -1,8 +1,8 @@ --- title: Warp Agent with the {{WARP_AUTOMATION_PLATFORM}} description: >- - Warp Agent is the {{WARP_AUTOMATION_PLATFORM}}'s default harness. It routes across leading models, has full - terminal access, and is the only harness that can orchestrate subagents. + Warp Agent is the default {{WARP_AUTOMATION_PLATFORM}} harness, with multi-model + routing, full terminal access, and cross-harness subagent orchestration. sidebar: label: "Warp Agent" --- diff --git a/src/content/docs/platform/self-hosting/index.mdx b/src/content/docs/platform/self-hosting/index.mdx index e0c346c0..df73af7a 100644 --- a/src/content/docs/platform/self-hosting/index.mdx +++ b/src/content/docs/platform/self-hosting/index.mdx @@ -1,9 +1,8 @@ --- title: Self-hosting overview description: >- - Run cloud agents on your own infrastructure. Choose between a managed - worker daemon orchestrated by the {{WARP_AUTOMATION_PLATFORM}} or unmanaged CLI-based execution you - control. + Run cloud agents on your own infrastructure with a managed worker daemon or + unmanaged CLI-based execution you control. --- import { VARS } from '@data/vars'; diff --git a/src/content/docs/platform/self-hosting/monitoring.mdx b/src/content/docs/platform/self-hosting/monitoring.mdx index 2188d57e..9b372cd8 100644 --- a/src/content/docs/platform/self-hosting/monitoring.mdx +++ b/src/content/docs/platform/self-hosting/monitoring.mdx @@ -3,9 +3,8 @@ title: Self-hosted worker monitoring sidebar: label: "Monitoring" description: >- - Monitor self-hosted {{WARP_AUTOMATION_PLATFORM}} workers with OpenTelemetry metrics. Export to - Prometheus, OTLP, or console to track worker health, task throughput, - and saturation. + Monitor self-hosted {{WARP_AUTOMATION_PLATFORM}} workers with OpenTelemetry + metrics via Prometheus, OTLP, or console export. --- import { VARS } from '@data/vars'; From f41eae42026e5f288865578aa0341f57e388ddc6 Mon Sep 17 00:00:00 2001 From: "warp-agent-staging[bot]" <240773466+warp-agent-staging[bot]@users.noreply.github.com> Date: Fri, 21 Aug 2026 23:33:39 +0000 Subject: [PATCH 2/3] Remove duplicate H1 and de-redundant Factory MCP title Starlight already renders the frontmatter title as the page H1, so the explicit H1 added by the SEO fix duplicated the page title. Also reworked the title to avoid repeating "Factory"/"Factories" against the sidebar section context. Co-Authored-By: Warp --- src/content/docs/factories/factory-mcp.mdx | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/src/content/docs/factories/factory-mcp.mdx b/src/content/docs/factories/factory-mcp.mdx index 353887fa..6d8ce964 100644 --- a/src/content/docs/factories/factory-mcp.mdx +++ b/src/content/docs/factories/factory-mcp.mdx @@ -1,5 +1,5 @@ --- -title: Factory MCP for Warp Factories +title: Factory MCP for coding agents description: >- Connect any coding agent to your team's factories to send in work, continue tasks locally, and hand results back. @@ -7,8 +7,6 @@ sidebar: label: "Factory MCP" --- -# Factory MCP for Warp Factories - Factory MCP is a hosted Model Context Protocol (MCP) server that connects coding agents to your team's factories, in both directions: the agent you already work with — in Warp or in any MCP-capable tool — can send work to a factory, or take work over from one by pulling a task down, continuing it locally, and handing the result back. The factory keeps a single record of each task throughout. Whether a change happens in the cloud or on your machine, it lands on the same task with the same history and conversation. A task is the factory's work item: the same unit of work that appears in the factory dashboard's [Activity view](/factories/factory-dashboard/#track-work-items-on-activity). From 095791599dd02e4ae193871f5c5eba2844fc2e44 Mon Sep 17 00:00:00 2001 From: "warp-agent-staging[bot]" <240773466+warp-agent-staging[bot]@users.noreply.github.com> Date: Fri, 21 Aug 2026 23:44:02 +0000 Subject: [PATCH 3/3] docs-seo-audit: stop instructing manual H1 sync/add Astro Starlight always renders the page H1 from the frontmatter title (or sidebar label/slug fallback) -- this repo's pages never contain a manual H1 in the markdown body, since that pattern was leftover behavior from the old GitBook-based docs platform. The skill previously told the audit to add or sync an H1 whenever a title or sidebar label changed, which is what produced the duplicate H1 on the Factory MCP page fixed earlier on this branch. Rewrite the guidance so the skill never adds/syncs a manual H1, and instead treats one found during the multiple_h1/missing_h1 checks as an incidental defect to remove. Co-Authored-By: Warp --- .agents/skills/docs-seo-audit/SKILL.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/.agents/skills/docs-seo-audit/SKILL.md b/.agents/skills/docs-seo-audit/SKILL.md index 38dd00e7..3e2722c8 100644 --- a/.agents/skills/docs-seo-audit/SKILL.md +++ b/.agents/skills/docs-seo-audit/SKILL.md @@ -118,7 +118,7 @@ Before making any changes, read these references: 2. **Meta descriptions come from frontmatter**. To fix a description, edit the `description:` field in the page's YAML frontmatter. 3. **OG and Twitter tags mirror title and description** automatically. No separate fix needed. 4. **Changing a sidebar config label has side effects**: it also changes the sidebar label, breadcrumbs, and prev/next pagination. URLs are NOT affected (URLs are based on the file path/slug). -5. **When changing a title, also update the H1** in the markdown file for consistency. +5. **Never add or edit a manual H1 heading in a markdown file.** Astro Starlight auto-generates the page's H1 from the frontmatter `title` (falling back to the sidebar label or slug, per the precedence in `references/starlight-seo.md`), so this repo's pages never write an explicit `# Heading` at the top of the body — that pattern is leftover behavior from the old GitBook-based docs platform. Changing a `title` or sidebar `label` never requires a matching H1 edit, because there is no H1 in the markdown to edit. If the audit's `multiple_h1` or `missing_h1` check flags a page and you find a manual H1 in its body, treat that as an incidental defect: remove the manual H1 (do not keep it in sync with the title) as its own cleanup, separate from any title/description fix. 6. **All titles, labels, and H1 headings must use sentence case.** Capitalize only the first word and proper nouns. Only recognized proper feature names retain their capitalization — check `AGENTS.md` and `.agents/references/terminology.md` for the canonical list. Common mistakes to avoid: - ✅ `Computer use for agents` — generic term, sentence case - ❌ `Computer Use for Agents` — not a proper feature name, don't capitalize @@ -151,13 +151,13 @@ When the audit flags these pages for `title_too_short`, exclude them from your f If you believe a new title should be added to this exceptions list, flag it for human review before proceeding. -### Sidebar config labels vs. H1 headings +### Sidebar config labels vs. page titles -Sidebar config labels (the `label` property in `src/sidebar.ts`) and H1 page headings are **intentionally different** in some cases. Do not change either to match the other unless you are fixing a genuine duplicate title collision. Specifically: +Sidebar config labels (the `label` property in `src/sidebar.ts`) and frontmatter `title` values are **intentionally different** in some cases. Do not change either to match the other unless you are fixing a genuine duplicate title collision. Specifically: - Do **not** add section-context prefixes (like "Terminal", "Warp", or "Agent") to short but accurate titles just because the title appears generic in isolation. Sidebar context already provides that disambiguation. - Do **not** rename sidebar config labels for pages in the exceptions list above. -- Do **not** sync sidebar config label text to match H1 headings (or vice versa) as a standalone change — the two are allowed to differ. +- Do **not** sync sidebar config label text to match the frontmatter `title` (or vice versa) as a standalone change — the two are allowed to differ. Neither one requires touching an H1 in the markdown body, since there isn't one (see Key principle #5). ### Fixing duplicate titles @@ -185,7 +185,7 @@ Example: - `agent-platform/capabilities/index.mdx`: `title: 'Capabilities overview'` + `sidebar.label: 'Overview'` - `platform/integrations/index.mdx`: `title: 'Integrations overview'` + `sidebar.label: 'Overview'` -When using this approach, also update the H1 in the markdown file to match the new `title`. +Do not add or update an H1 in the markdown file — Starlight renders the page's H1 from this frontmatter `title` automatically (see Key principle #5 above). #### Alternative: rename the sidebar config label @@ -193,7 +193,7 @@ If the short label is not intentional, rename the `label` in `src/sidebar.ts` to - Before: `{ slug: 'agent-platform/local-agents', label: 'Overview' }` + `{ slug: 'platform', label: 'Overview' }` - After: `{ slug: 'agent-platform/local-agents', label: 'Local agents overview' }` + `{ slug: 'platform', label: 'Cloud agents overview' }` -When changing a sidebar config label, also update the H1 in the markdown file for consistency. +Do not add or update an H1 in the markdown file for this — Starlight renders the page's H1 from the frontmatter `title` (or the slug when no `title` is set), never from the sidebar label (see Key principle #5 above). ### Fixing missing descriptions @@ -219,7 +219,7 @@ After making fixes, review every change before presenting to the user. Run throu - **Does this still mean the same thing?** Titles and descriptions must accurately represent the page content. Read the actual page before writing or rewriting anything. Never invent features, capabilities, or details that aren't on the page. If unsure what the page covers, read it first. - **Did I introduce a new duplicate?** Scan the full sidebar config in `src/sidebar.ts`. Verify every label is unique within the site. This is the most common mistake — fixing one duplicate by picking a name that collides with an existing entry. -- **Does the H1 match?** Every sidebar config label change needs a corresponding H1 update in the markdown file. Mismatches between sidebar label and page heading confuse readers. +- **Did I leave any manual H1 behind?** Scan every file you touched for a body-level `# Heading` and remove it — Starlight already renders the page's H1 from frontmatter `title`, so a manual H1 is always a duplicate, never something to add or sync with a title/label change. - **Is the terminology right?** Cross-check against `AGENTS.md` and how the feature is actually referred to in the existing docs. Don't rename things to terms that aren't used elsewhere in the docs. - **Is the casing right?** All labels and H1 headings must use sentence case. Proper product feature names (e.g., "Agent Mode", "Codebase Context", "Admin Panel", "Remote Control", "Warp Drive") retain their capitalization, but generic terms ("overview", "quickstart", "agents", "notifications") are lowercase. Never use title case. - **Does this read naturally in context?** Consider how the title appears (a) as a sidebar label under its section header, and (b) as a search result: `{Title} | {Topic} | Warp`. If it sounds awkward or uses internal jargon that users wouldn't recognize, rephrase.