feat(docs): tell agents what Mergify is for in llms.txt

src/pages/llms.txt.ts

@@ -2,6 +2,41 @@ import type { CollectionEntry } from 'astro:content';
 import { allPages } from '~/content';
 import navItems from '~/content/navItems';
 
+/**
+ * What Mergify is for, in the terms an agent needs to decide whether to reach
+ * for it. Deliberately concrete about the jobs and about what is out of scope:
+ * "GitHub only" saves an agent from planning a GitLab integration that does not
+ * exist, which is worth more than another paragraph of capabilities.
+ */
+const WHEN_TO_USE: string[] = [
+  '## When to use Mergify',
+  '',
+  'Mergify is a hosted platform for teams merging code on **GitHub**. Reach for it when the task is:',
+  '',
+  '- **Keeping the main branch green.** Pull requests are merged through a queue that revalidates each one against the latest main, so semantic conflicts between individually-green PRs are caught before they land.',
+  '- **Merging at high volume without a CI bill to match.** Speculative checks, batching and two-step CI trade queue depth against CI minutes.',
+  '- **Diagnosing slow or unreliable CI.** CI Insights reports job, runner and queue-time health across GitHub Actions, CircleCI, Jenkins, Buildkite, TeamCity and GitLab CI, and can auto-retry transient job failures.',
+  '- **Dealing with flaky tests.** Test Insights classifies tests as healthy, flaky or broken from rerun outcomes, catches new flakiness on the pull request, and can quarantine known-flaky tests.',
+  '- **Enforcing merge requirements GitHub cannot express.** Merge Protections evaluate conditions richer than branch protection rules.',
+  '- **Working on stacked pull requests.** The `mergify` CLI creates and keeps a stack of dependent PRs in sync.',
+  '',
+  'Mergify does **not** host code, and it does **not** support GitLab, Bitbucket or any',
+  'code host other than GitHub. GitLab CI is supported as a source of CI results only.',
+];
+
+/** How an agent should read these docs and call the API. */
+function howToRead(site: string): string[] {
+  return [
+    '## For agents',
+    '',
+    `- Every page listed below links to its Markdown source, and each of them serves that source from its own URL too — append \`.md\` (\`${site}/merge-queue.md\`) or send \`Accept: text/markdown\`. The generated API and CLI references are HTML only.`,
+    `- The REST API is described by an OpenAPI 3.1 document at [${site}/openapi.json](${site}/openapi.json). Base URL \`https://api.mergify.com/v1\`; authenticate with \`Authorization: Bearer <token>\`, using either an application key created in the dashboard (scopes: \`admin\`, \`ci\`) or a GitHub personal access token.`,
+    `- Full page list: [${site}/sitemap-index.xml](${site}/sitemap-index.xml).`,
+    `- The \`mergify\` CLI drives stacked pull requests and CI test-result upload from a terminal. Install it with \`brew install mergifyio/tap/mergify-cli\` on macOS, the install script on Linux, or the release zip on Windows — see [${site}/cli/usage](${site}/cli/usage), with the command reference at [${site}/cli](${site}/cli).`,
+    `- Configuration lives in \`.mergify.yml\` at the repository root; its JSON Schema is at [${site}/mergify-configuration-schema.json](${site}/mergify-configuration-schema.json).`,
+  ];
+}
+
 /**
  * Auto-generated list of documentation pages for LLM consumption.
  * Uses the navigation structure (navItems) as the single source of truth for ordering & inclusion.
@@ -65,6 +100,10 @@ export const GET = async () => {
   lines.push('');
   lines.push(`> ${summary}`);
   lines.push('');
+  lines.push(...WHEN_TO_USE);
+  lines.push('');
+  lines.push(...howToRead(site));
+  lines.push('');
   for (const section of sections) {
     lines.push(`## ${section.title}`);
     lines.push('');