From 93d5682c65fa20967064ebf2d705c74f26b3bcbe Mon Sep 17 00:00:00 2001
From: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com>
Date: Tue, 12 May 2026 08:04:29 -1000
Subject: [PATCH] Link OpenAPI spec from llms.txt and robots.txt

- Add src/pages/openapi.yaml.ts endpoint to serve the raw spec at /openapi.yaml
- Add optionalLinks to starlight-llms-txt config so llms.txt references the spec
- Add Llms-Txt and OpenAPI directives to robots.txt

Co-Authored-By: Oz <oz-agent@warp.dev>
---
 astro.config.mjs          |  7 +++++++
 public/robots.txt         |  2 ++
 src/pages/openapi.yaml.ts | 18 ++++++++++++++++++
 3 files changed, 27 insertions(+)
 create mode 100644 src/pages/openapi.yaml.ts

diff --git a/astro.config.mjs b/astro.config.mjs
index d22733a9..10fac584 100644
--- a/astro.config.mjs
+++ b/astro.config.mjs
@@ -148,6 +148,13 @@ export default defineConfig({
 				// widely consumed by AI agents.
 				starlightLlmsTxt({
 					projectName: 'Warp',
+					optionalLinks: [
+						{
+							label: 'Oz Agent API (OpenAPI spec)',
+							url: 'https://docs.warp.dev/openapi.yaml',
+							description: 'Machine-readable OpenAPI 3.0 specification for the Oz Agent API.',
+						},
+					],
 				// Excludes pages that cause a stack overflow in hast-util-to-text
 				// due to their size. The upstream plugin only applies `exclude` to
 				// llms-small.txt; our patch (patches/starlight-llms-txt+0.8.1.patch)
diff --git a/public/robots.txt b/public/robots.txt
index 988aefb3..53432134 100644
--- a/public/robots.txt
+++ b/public/robots.txt
@@ -5,3 +5,5 @@ Disallow: /*?*ask=*
 Content-Signal: ai-train=yes, search=yes, ai-input=yes
 
 Sitemap: https://docs.warp.dev/sitemap-index.xml
+Llms-Txt: https://docs.warp.dev/llms.txt
+OpenAPI: https://docs.warp.dev/openapi.yaml
diff --git a/src/pages/openapi.yaml.ts b/src/pages/openapi.yaml.ts
new file mode 100644
index 00000000..801660a5
--- /dev/null
+++ b/src/pages/openapi.yaml.ts
@@ -0,0 +1,18 @@
+import type { APIRoute } from 'astro';
+import fs from 'node:fs';
+
+export const prerender = true;
+
+/**
+ * Serves the raw Oz Agent API OpenAPI spec at /openapi.yaml so LLMs, crawlers,
+ * and developer tooling can consume the machine-readable definition directly.
+ *
+ * The spec source of truth is `developers/agent-api-openapi.yaml` (same file
+ * that `src/pages/api.astro` reads at build time for the Scalar reference).
+ */
+export const GET: APIRoute = async () => {
+	const yaml = fs.readFileSync('developers/agent-api-openapi.yaml', 'utf-8');
+	return new Response(yaml, {
+		headers: { 'Content-Type': 'text/yaml; charset=utf-8' },
+	});
+};