Link OpenAPI spec from llms.txt and robots.txt (#69)

- 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>

Author: rachaelrenk

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)

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

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' },
+	});
+};