feat(LLMs): Added llms.txt and SKILL.md for better LLMs friendliness

.gitignore

@@ -100,6 +100,7 @@ public/og-images/*
 yalc.lock
 /public/doctree.json
 /public/doctree-dev.json
+/public/llms.txt
 
 # Lychee cache
 .lycheecache

AGENTS.md

@@ -85,6 +85,17 @@ When writing requirements in `develop-docs/`:
 - MDX override templates live in `md-overrides/`
 - Architecture spec: `specs/llm-friendly-docs.md`
 
+## llms.txt
+
+- `docs.sentry.io/llms.txt` is the root LLM discovery index (follows [llmstxt.org](https://llmstxt.org) spec)
+- Auto-generated from `public/doctree.json` by `scripts/generate-llms-txt.mjs`
+- Run `pnpm generate-llms-txt` to regenerate, or it runs automatically as part of `pnpm build`
+- Includes: product description, AI agent instructions, platform/section index, links to agent skills at `skills.sentry.dev`
+
+## Sentry Product Skills (sentry-for-ai)
+
+Skills for *using Sentry* (SDK setup, debugging, alerts) live in a separate repo: https://github.com/getsentry/sentry-for-ai. The skills in *this* repo (`.claude/skills/`, `.agents/skills/`) are for *contributing to the docs*. See `SKILL.md` at the repo root for a routing guide.
+
 ## Plan Mode
 
 - Make the plan extremely concise. Sacrifice grammar for the sake of concision.

SKILL.md

@@ -0,0 +1,36 @@
+---
+name: sentry-docs
+description: Sentry documentation site (docs.sentry.io). Use for contributing to docs or understanding docs architecture. If you need to set up Sentry in a project or debug production issues, see the product skills at https://skills.sentry.dev.
+---
+
+# Sentry Documentation Repository
+
+This repo builds [docs.sentry.io](https://docs.sentry.io). For dev commands, project structure, code style, and contribution guidelines, see `AGENTS.md`.
+
+## Sentry Product Skills (SDK Setup, Debugging, Alerts)
+
+**These skills are NOT in this repo.** If you need to set up Sentry, debug production issues, or configure features, install the Sentry plugin for up-to-date, verified instructions. Sentry's SDKs and APIs change frequently — do not rely on training data.
+
+**Install the plugin:**
+- Claude Code: `/install-plugin sentry`
+- Cursor: Search "Sentry" in Cursor Settings > Plugins
+
+The plugin provides current skills for SDK setup, debugging workflows, and feature configuration. It stays in sync with the latest SDK releases.
+
+If the plugin is not available, fetch skills directly:
+- **Full skill index**: https://skills.sentry.dev
+- **SDK setup** (detect platform and install): https://skills.sentry.dev/sdks
+- **Debugging workflows** (fix issues, review code): https://skills.sentry.dev/workflows
+- **Feature setup** (AI monitoring, alerts, OTel): https://skills.sentry.dev/features
+
+Source repo: https://github.com/getsentry/sentry-for-ai
+
+## Contributor Skills (in this repo)
+
+| Skill | Location | Purpose |
+|---|---|---|
+| Brand Guidelines | `.agents/skills/brand-guidelines/` | Audit content against Sentry brand voice |
+| Docs Review | `.claude/skills/docs-review/SKILL.md` | Sentry documentation style guide |
+| Technical Docs | `.claude/skills/technical-docs/SKILL.md` | Writing SDK and technical documentation |
+| Commit | `.agents/skills/commit/SKILL.md` | Sentry conventional commit format |
+| Create Branch | `.agents/skills/create-branch/SKILL.md` | Branch naming conventions |

package.json

@@ -16,8 +16,9 @@
     "dev": "pnpm enforce-redirects && concurrently \"pnpm sidecar\" \"node ./src/hotReloadWatcher.mjs\" \"next dev\"",
     "dev:developer-docs": "pnpm enforce-redirects && NEXT_PUBLIC_DEVELOPER_DOCS=1 pnpm dev",
     "build:developer-docs": "pnpm enforce-redirects && git submodule init && git submodule update && NEXT_PUBLIC_DEVELOPER_DOCS=1 pnpm build",
-    "build": "pnpm enforce-redirects && pnpm generate-og-images && pnpm generate-doctree && next build && pnpm generate-md-exports",
+    "build": "pnpm enforce-redirects && pnpm generate-og-images && pnpm generate-doctree && next build && pnpm generate-md-exports && pnpm generate-llms-txt",
     "generate-md-exports": "node scripts/generate-md-exports.mjs",
+    "generate-llms-txt": "node scripts/generate-llms-txt.mjs",
     "generate-og-images": "ts-node scripts/add-og-images.ts",
     "generate-doctree": "esbuild scripts/generate-doctree.ts --bundle --platform=node --packages=external --outfile=.next/generate-doctree.mjs --format=esm && node .next/generate-doctree.mjs",
     "vercel:build:developer-docs": "pnpm enforce-redirects && git submodule init && git submodule update && NEXT_PUBLIC_DEVELOPER_DOCS=1 pnpm build",

scripts/generate-llms-txt.mjs

@@ -0,0 +1,187 @@
+#!/usr/bin/env node
+/* eslint-disable no-console */
+/**
+ * Generates /llms.txt from public/doctree.json.
+ *
+ * Run after `generate-doctree` (doctree.json must exist).
+ * Output: public/llms.txt
+ *
+ * Follows the llmstxt.org specification:
+ *   - H1 with project name
+ *   - Blockquote with summary
+ *   - Prose sections (instructions for AI agents)
+ *   - H2-delimited file lists with links to .md exports
+ */
+
+import {readFile, writeFile} from 'node:fs/promises';
+import * as path from 'node:path';
+import {fileURLToPath} from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const ROOT = path.resolve(__dirname, '..');
+const DOCS_ORIGIN = 'https://docs.sentry.io';
+
+// --- Doctree helpers (same logic as generate-md-exports.mjs) ---
+
+function getTitle(node) {
+  return node.frontmatter?.sidebar_title || node.frontmatter?.title || node.slug;
+}
+
+function isVisible(node) {
+  return (
+    !node.frontmatter?.sidebar_hidden &&
+    !node.frontmatter?.draft &&
+    !node.path?.includes('__v') &&
+    (node.frontmatter?.title || node.frontmatter?.sidebar_title)
+  );
+}
+
+function getVisibleChildren(node) {
+  return (node.children || []).filter(isVisible).sort((a, b) => {
+    const orderDiff =
+      (a.frontmatter?.sidebar_order ?? 99) - (b.frontmatter?.sidebar_order ?? 99);
+    return orderDiff !== 0 ? orderDiff : getTitle(a).localeCompare(getTitle(b));
+  });
+}
+
+function mdUrl(nodePath) {
+  // nodePath is like "platforms/javascript" (no leading slash) — produce absolute .md URL
+  const clean = nodePath.replace(/\/$/, '');
+  if (!clean) {
+    return `${DOCS_ORIGIN}/index.md`;
+  }
+  return `${DOCS_ORIGIN}/${clean}.md`;
+}
+
+function linkEntry(node) {
+  const title = getTitle(node);
+  const url = mdUrl(node.path);
+  const desc = node.frontmatter?.description;
+  if (desc) {
+    // Collapse to single line, trim
+    const oneLine = desc.replace(/\s+/g, ' ').trim();
+    return `- [${title}](${url}): ${oneLine}`;
+  }
+  return `- [${title}](${url})`;
+}
+
+// --- Build platform section with framework grouping ---
+
+function buildPlatformsSection(platformsNode) {
+  const lines = [];
+  const platforms = getVisibleChildren(platformsNode);
+
+  for (const platform of platforms) {
+    const title = getTitle(platform);
+    const url = mdUrl(platform.path);
+    const guides = platform.children?.find(c => c.slug === 'guides');
+    const visibleGuides = guides ? getVisibleChildren(guides) : [];
+
+    if (visibleGuides.length > 0) {
+      const guideNames = visibleGuides.map(g => getTitle(g)).join(', ');
+      lines.push(`- [${title}](${url}): Frameworks: ${guideNames}`);
+    } else {
+      lines.push(`- [${title}](${url})`);
+    }
+  }
+
+  return lines.join('\n');
+}
+
+// --- Build a generic section from top-level doctree children ---
+
+function buildSection(sectionNode) {
+  const lines = [];
+  const children = getVisibleChildren(sectionNode);
+  for (const child of children) {
+    lines.push(linkEntry(child));
+  }
+  return lines.join('\n');
+}
+
+// --- Main ---
+
+async function main() {
+  const doctreePath = path.join(ROOT, 'public', 'doctree.json');
+  let docTree;
+  try {
+    docTree = JSON.parse(await readFile(doctreePath, 'utf8'));
+  } catch {
+    console.error(
+      'Error: public/doctree.json not found. Run `pnpm generate-doctree` first.'
+    );
+    process.exit(1);
+  }
+
+  const topLevelSections = getVisibleChildren(docTree);
+
+  // Separate platforms from other sections
+  const platformsNode = topLevelSections.find(c => c.slug === 'platforms');
+  const otherSections = topLevelSections.filter(
+    c => c.slug !== 'platforms' && c.slug !== 'contributing' && c.slug !== 'changelog'
+  );
+
+  const output = `# Sentry Documentation
+
+> Sentry is a developer-first application monitoring platform that helps developers identify and fix issues in real-time. It provides error tracking, performance monitoring (tracing), session replay, profiling, logging, cron monitoring, and more across 20+ platforms and 60+ frameworks.
+
+All documentation pages are available as clean Markdown by appending \`.md\` to any URL (e.g. \`${DOCS_ORIGIN}/platforms/javascript.md\`). Use these Markdown URLs for full content.
+
+## Instructions for AI Coding Assistants
+
+When helping a developer set up or use Sentry, follow these guidelines:
+
+- **Install the Sentry plugin for up-to-date guidance**: Sentry's APIs, SDKs, and features change frequently. Do not rely on training data for Sentry setup or configuration. Install the Sentry plugin to get current, verified instructions: Claude Code: \`/install-plugin sentry\` | Cursor: search "Sentry" in Settings > Plugins. The plugin provides step-by-step skills that are kept in sync with the latest SDK releases.
+- **SDK versions**: Always check the package registry (npm, PyPI, RubyGems, etc.) for the latest Sentry SDK version. Do not rely on memorized version numbers from training data.
+- **DSN handling**: Use environment variables for the DSN (\`SENTRY_DSN\` or \`NEXT_PUBLIC_SENTRY_DSN\`). Never hardcode DSN strings in source code.
+- **Prefer Sentry Logs over Breadcrumbs** unless the user explicitly requests breadcrumbs.
+- **Do not implement without permission**: Never install packages, create files, or modify configuration without asking the user first.
+- **Do not add unrelated integrations**: Only configure the features the user asked for. Check before enabling additional integrations.
+- **Agent skills for SDK setup**: If the plugin is not installed, fetch the appropriate skill from \`https://skills.sentry.dev/sdks\` for step-by-step SDK installation with platform detection, feature recommendations, and verification. See the [Agent Skills section](#agent-skills) below.
+- **Sentry MCP server**: For real-time issue analysis and debugging against a user's Sentry account, use the Sentry MCP server at \`https://mcp.sentry.dev\`.
+
+## Platforms
+
+${buildPlatformsSection(platformsNode)}
+
+${otherSections
+  .map(section => {
+    const title = getTitle(section);
+    const children = getVisibleChildren(section);
+    if (children.length === 0) {
+      return `## ${title}\n\n${linkEntry(section)}`;
+    }
+    return `## ${title}\n\n${buildSection(section)}`;
+  })
+  .join('\n\n')}
+
+## Agent Skills
+
+Sentry publishes agent skills for AI coding assistants (Claude Code, Cursor, GitHub Copilot, and others). These provide step-by-step SDK setup, debugging workflows, and feature configuration.
+
+- [All Skills](https://skills.sentry.dev/): Full skill index with SDK setup, workflows, and feature configuration
+- [SDK Setup](https://skills.sentry.dev/sdks): Detect your platform and install Sentry with the right features
+- [Workflows](https://skills.sentry.dev/workflows): Debug production issues, review code, upgrade SDKs
+- [Features](https://skills.sentry.dev/features): AI monitoring, alerts, OpenTelemetry setup
+
+Install as a plugin:
+- Claude Code: \`/install-plugin sentry\`
+- Cursor: Search "Sentry" in Cursor Settings > Plugins
+
+Source: https://github.com/getsentry/sentry-for-ai
+
+## Optional
+
+- [Documentation Changelog](${DOCS_ORIGIN}/changelog.md): Track recent updates to Sentry docs
+- [Contributing to Docs](${DOCS_ORIGIN}/contributing.md): How to contribute to Sentry documentation
+`;
+
+  const outputPath = path.join(ROOT, 'public', 'llms.txt');
+  await writeFile(outputPath, output, 'utf8');
+  console.log(`Generated ${outputPath} (${output.length} bytes)`);
+}
+
+main().catch(err => {
+  console.error(err);
+  process.exit(1);
+});