TRA-862: publish agent-friendly documentation surfaces

docs/api/README.mdx

@@ -26,6 +26,7 @@ export const SpecLinks = () => {
 - New to the API? **[Quickstart](./quickstart)** — mint a key, make your first call, round-trip a resource. ~10 minutes.
 - Already know the shape? **[Interactive reference](/api)** — every endpoint, rendered from the OpenAPI spec that ships with each release.
 - Generating a client? Point your generator at <SpecLinks />. The same URLs feed the [API client guide](./postman) (Postman, Insomnia, Bruno, Hoppscotch).
+- Static fallback for Markdown consumers: production specs are `https://app.trakrf.id/api/openapi.json` and `https://app.trakrf.id/api/openapi.yaml`; preview deployments use the matching `app.preview.trakrf.id` host.
 
 ## Concept guides
 

docusaurus.config.ts

@@ -62,6 +62,27 @@ const config: Config = {
         ],
       },
     ],
+    [
+      "docusaurus-plugin-llms",
+      {
+        generateLLMsTxt: true,
+        generateLLMsFullTxt: true,
+        generateMarkdownFiles: true,
+        preserveDirectoryStructure: true,
+        addMdExtension: true,
+        excludeImports: true,
+        removeDuplicateHeadings: true,
+        customLLMFiles: [
+          {
+            filename: "llms-api.txt",
+            includePatterns: ["api/**/*.md", "api/**/*.mdx"],
+            fullContent: true,
+            title: "TrakRF API Documentation",
+            description: "Integrator-focused API reference and conventions",
+          },
+        ],
+      },
+    ],
   ],
 
   presets: [

package.json

@@ -14,7 +14,8 @@
     "swizzle": "docusaurus swizzle",
     "write-translations": "docusaurus write-translations",
     "write-heading-ids": "docusaurus write-heading-ids",
-    "check:contributing": "node scripts/check-contributing.mjs"
+    "check:contributing": "node scripts/check-contributing.mjs",
+    "check:agent-docs": "node scripts/check-agent-docs.mjs"
   },
   "dependencies": {
     "@docusaurus/core": "3.9.2",
@@ -32,6 +33,7 @@
     "@docusaurus/module-type-aliases": "3.9.2",
     "@docusaurus/tsconfig": "3.9.2",
     "@docusaurus/types": "3.9.2",
+    "docusaurus-plugin-llms": "0.6.0",
     "prettier": "^3.0.0",
     "typescript": "~5.6.2"
   },

scripts/check-agent-docs.mjs

@@ -0,0 +1,54 @@
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+
+const buildDir = resolve("build");
+const requiredFiles = ["llms.txt", "llms-full.txt", "llms-api.txt"];
+const markdownFiles = [
+  "docs/api/authentication.md",
+  "docs/api/errors.md",
+  "docs/api/design-notes.md",
+  "docs/api/quickstart.md",
+];
+
+async function readBuildFile(file) {
+  try {
+    return await readFile(resolve(buildDir, file), "utf8");
+  } catch (error) {
+    throw new Error(`Missing build/${file}: ${error.message}`);
+  }
+}
+
+function assert(condition, message) {
+  if (!condition) throw new Error(message);
+}
+
+const files = new Map(
+  await Promise.all(
+    [...requiredFiles, ...markdownFiles].map(async (file) => [
+      file,
+      await readBuildFile(file),
+    ]),
+  ),
+);
+
+const llms = files.get("llms.txt");
+const api = files.get("llms-api.txt");
+
+assert(
+  /\[[^\]]+\]\([^\s)]+\.md\)/.test(llms),
+  "llms.txt does not link to Markdown mirrors",
+);
+assert(api.includes("TrakRF API"), "llms-api.txt does not contain API content");
+assert(
+  !/\/docs\/(?:user-guide|app-tour)\//.test(api),
+  "llms-api.txt includes user-guide or app-tour content",
+);
+
+for (const file of markdownFiles) {
+  assert(
+    !/^\s*<!doctype html/i.test(files.get(file)),
+    `build/${file} is an HTML document, not Markdown`,
+  );
+}
+
+console.log("Agent documentation build output is complete and API-scoped.");

src/pages/index.tsx

@@ -18,6 +18,10 @@ function HomepageHeader() {
           {siteConfig.title}
         </Heading>
         <p className="hero__subtitle">{siteConfig.tagline}</p>
+        <p>
+          Coding with an agent? Browse our machine-readable documentation at{" "}
+          <a href="/llms.txt">/llms.txt</a>.
+        </p>
         <div style={{ marginTop: "1.5rem" }}>
           <Link
             className="button button--primary button--lg"