docs: improve agent-friendly docs score (AFDocs quick wins) by rachaelrenk · Pull Request #23 · warpdotdev/docs

rachaelrenk · 2026-05-05T19:20:11Z

Summary

Addresses failing AFDocs scorecard checks to improve the agent-friendly docs score from 82/100 (B) toward 95+ (A).

Changes

Task 1: llms.txt directive on all pages

HTML: Added a visually-hidden div in CustomHeader.astro with a link to /llms.txt and a note about .md URL availability.
Markdown: Modified docs-markdown-integration.js to prepend a blockquote directive to every generated .md file.

Task 2: Content negotiation middleware

New src/middleware.ts -- Astro middleware that rewrites requests to the .md variant when agents send Accept: text/markdown or are identified by user-agent. Uses the existing shouldServeMarkdown() helper from src/lib/docs-markdown.js.

Task 3: Content-start-position verification

Verified the link rel alternate type text/markdown already appears early in head -- no repositioning needed. Tasks 1+2 are the primary mitigations.

Task 4: llms.txt coverage improvement

Fixed university/** to guides/** in the starlightLlmsTxt customSets config (directory was renamed but config was not updated).
Added community pages (contributing, open-source-partnership, refer-a-friend) to the Support customSet.
Corrected the exclude config comment to clarify it only applies to llms-small.txt, not llms-full.txt.

Task 7: MCP discovery file

Added public/.well-known/mcp.json pointing to the existing Kapa MCP at https://warp.mcp.kapa.ai/sse. Team consensus (Petra, Ben, Hong Yi) was that a custom MCP server is not needed -- Warp has built-in product knowledge, and this check is primarily a Mintlify upsell.

AFDocs checks addressed

Check	Before	After
llms-txt-directive-html	FAIL	PASS
llms-txt-directive-md	FAIL	PASS
content-negotiation	FAIL	PASS
content-start-position	FAIL	Mitigated
llms-txt-coverage	80%	Improved
MCP Server Discoverable	FAIL	PASS

References

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

- Add llms.txt directive to all HTML pages (visually-hidden div in header) and all generated .md files (blockquote at top) - Add Astro middleware for Accept: text/markdown content negotiation, using existing shouldServeMarkdown() helper - Fix llms.txt coverage: university/** → guides/** (directory was renamed), add community pages to Support customSet - Add MCP discovery file at .well-known/mcp.json pointing to Kapa MCP - Verify <link rel=alternate type=text/markdown> already appears early in <head> — no repositioning needed Checks addressed: llms-txt-directive-html (FAIL → PASS) llms-txt-directive-md (FAIL → PASS) content-negotiation (FAIL → PASS) content-start-position (mitigated via Tasks 1+2) llms-txt-coverage (80% → improved) MCP Server Discoverable (FAIL → PASS) Co-Authored-By: Oz <oz-agent@warp.dev>

vercel · 2026-05-05T19:20:16Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
docs	Ready	Preview, Comment	May 5, 2026 10:25pm

hongyi-chen · 2026-05-05T21:47:17Z

+{
+  "name": "Warp Documentation",
+  "description": "Search and retrieve Warp documentation — the agentic development environment and Oz, Warp's programmable agent platform.",
+  "url": "https://warp.mcp.kapa.ai/sse",


What do we have to do to get this to work? Going to the URL gives me a 404. cc @dannyneira

The Kapa MCP server uses OAuth authentication at the base URL, not an SSE endpoint at /sse. Remove the incorrect path and transport field. Co-Authored-By: Oz <oz-agent@warp.dev>

rachaelrenk · 2026-05-05T22:25:44Z

Good catch @hongyi-chen, the /sse path was wrong, fixed in d93f0a1 (base URL is just https://warp.mcp.kapa.ai).

Browsing directly will still return a 401 — that's expected. The Kapa MCP server uses OAuth authentication, so only MCP clients that handle the OAuth flow can connect (e.g., Claude, Cursor). The .well-known/mcp.json file is a discovery endpoint that tells those clients where to connect, not a human-facing URL.

… counts - Fix stale /sse path in afdocs-fix MCP example (matches PR #23 fix) - Add URL validation in afdocs_audit.mjs to prevent shell injection - Remove hardcoded baseline score from SKILL.md reporting instructions - Soften hardcoded page counts in known-exceptions.md (varies by run) - Scope page-size exception to /changelog/ only, not all large pages Co-Authored-By: Oz <oz-agent@warp.dev>

#25) * docs: add AFDocs audit skill for agent-friendly docs monitoring Add a reusable skill (.agents/skills/afdocs-audit/) that runs the AFDocs scorecard against docs.warp.dev and produces a structured report. Follows the same pattern as the existing docs-seo-audit skill. Includes: - SKILL.md with instructions for running, reporting, and Slack notifications - afdocs_audit.mjs wrapper script that runs npx afdocs check --format json, parses the output, and produces a structured report with scores, issues, and fix guidance - references/known-exceptions.md documenting expected failures and false positives (content-start-position, markdown-content-parity, page-size) The skill is designed to be run by a scheduled Oz agent (weekly cadence) to monitor the docs site's agent-friendliness score over time. Co-Authored-By: Oz <oz-agent@warp.dev> * docs: add afdocs-fix remediation skill (Part B) Add the companion skill that reads the afdocs-audit output and applies automated fixes for each failing check. Includes: - Fix procedures for each AFDocs check (llms.txt directive, content negotiation middleware, llms.txt coverage, MCP discovery, etc.) - Code snippets and file paths for each fix - Diagnostic steps for coverage mismatches - Clear separation of automatable vs. non-automatable checks - PR conventions (title prefix, labels, co-author) This is the 'fix layer' that a scheduled Oz agent runs after the audit skill to automatically remediate regressions. Co-Authored-By: Oz <oz-agent@warp.dev> * chore: hardcode #growth-docs channel ID (C09BVK0PL3Y) in afdocs-audit skill Co-Authored-By: Oz <oz-agent@warp.dev> * chore: simplify PR conventions — shorten prefix, remove nonexistent label Co-Authored-By: Oz <oz-agent@warp.dev> * chore: review fixes — stale MCP URL, URL validation, soften hardcoded counts - Fix stale /sse path in afdocs-fix MCP example (matches PR #23 fix) - Add URL validation in afdocs_audit.mjs to prevent shell injection - Remove hardcoded baseline score from SKILL.md reporting instructions - Soften hardcoded page counts in known-exceptions.md (varies by run) - Scope page-size exception to /changelog/ only, not all large pages Co-Authored-By: Oz <oz-agent@warp.dev> * fix: deploy middleware as Vercel Edge Function for content negotiation The Astro middleware in src/middleware.ts was not running at request time for pre-rendered (static) pages. The default middlewareMode ('classic') only executes middleware at build time for static pages, so Accept: text/markdown requests were served HTML from Vercel's CDN cache. Setting middlewareMode: 'edge' deploys the middleware as a separate Vercel Edge Function that runs at request time for ALL requests, including static pages. This enables content negotiation so agents sending Accept: text/markdown get clean markdown automatically. Co-Authored-By: Oz <oz-agent@warp.dev> * chore: revert Slack channel to placeholder per review feedback Reverts the hardcoded #growth-docs channel ID (C09BVK0PL3Y) back to a <CHANNEL_ID> placeholder, matching the docs-seo-audit pattern. The channel is specified in the scheduled agent's prompt, not in the skill. Co-Authored-By: Oz <oz-agent@warp.dev> --------- Co-authored-by: Oz <oz-agent@warp.dev>

cla-bot Bot added the cla-signed label May 5, 2026

vercel Bot deployed to Preview May 5, 2026 19:21 View deployment

rachaelrenk self-assigned this May 5, 2026

rachaelrenk changed the title ~~feat: improve agent-friendly docs score (AFDocs quick wins)~~ docs: improve agent-friendly docs score (AFDocs quick wins) May 5, 2026

hongyi-chen approved these changes May 5, 2026

View reviewed changes

fix: use correct Kapa MCP base URL (remove /sse path)

d93f0a1

The Kapa MCP server uses OAuth authentication at the base URL, not an SSE endpoint at /sse. Remove the incorrect path and transport field. Co-Authored-By: Oz <oz-agent@warp.dev>

vercel Bot deployed to Preview May 5, 2026 22:25 View deployment

rachaelrenk merged commit de2d3ea into main May 5, 2026
8 checks passed

This was referenced May 5, 2026

fix: deploy middleware as Vercel Edge Function for content negotiation #26

Closed

docs: add AFDocs audit + fix skills for agent-friendly docs monitoring #25

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: improve agent-friendly docs score (AFDocs quick wins)#23

docs: improve agent-friendly docs score (AFDocs quick wins)#23
rachaelrenk merged 2 commits intomainfrom
rachael/afdocs-quick-wins

rachaelrenk commented May 5, 2026 •

edited

Loading

Uh oh!

vercel Bot commented May 5, 2026 •

edited

Loading

Uh oh!

hongyi-chen May 5, 2026

Uh oh!

rachaelrenk commented May 5, 2026 •

edited

Loading

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

rachaelrenk commented May 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Changes

AFDocs checks addressed

References

Uh oh!

vercel Bot commented May 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

hongyi-chen May 5, 2026

Choose a reason for hiding this comment

Uh oh!

rachaelrenk commented May 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

rachaelrenk commented May 5, 2026 •

edited

Loading

vercel Bot commented May 5, 2026 •

edited

Loading

rachaelrenk commented May 5, 2026 •

edited

Loading