docs: update AGENTS.md with Link static file behavior and llms.txt rule

quantizor · quantizor · commit 6b05686db206 · 2026-04-09T13:27:23.000-04:00
diff --git a/AGENTS.md b/AGENTS.md
@@ -6,6 +6,8 @@ styled-components documentation website. Next.js, MDX, styled-components.
 
 Before editing anything that touches styled-components APIs (`createTheme`, `ThemeProvider`, `createGlobalStyle`, `ServerStyleSheet`, `StyleSheetManager`, `stylisPluginRSC`), read `public/llms.txt`. It's the battle-tested v6.4 usage guide with real gotchas: `ThemeProvider` must receive the raw theme object (not the `createTheme` output — passing the output produces self-referential `var(--x, fallback)` CSS), `theme.vars` gives bare custom property names for dark mode overrides, `@property` registration is required for animatable tokens, etc. Trust `llms.txt` over training-data assumptions.
 
+`llms.txt` is a first-class doc — when MDX docs change (API, SSR, theming, gotchas), update `llms.txt` in the same pass. It describes user-facing behavior, not implementation details. The same "artifacts describe behavior, not process" standard applies.
+
 ## Principles
 
 1. Verify before building -- read the file before editing. Assumptions cause build failures.
@@ -26,7 +28,7 @@ Before editing anything that touches styled-components APIs (`createTheme`, `The
 
 **Theme:** Three states (light/dark/auto). Raw `<script>` in `<head>` before stylesheets sets the class — not `next/script`. `data-theme="dark"` synced for DocSearch. Toggle icon shows current mode.
 
-**Navigation:** Sidebar lives in `ClientLayout` (root layout) — persists across navigations via `SidebarFoldProvider` context. Search (DocSearch, module-level singleton) at top, then Home, Agents, Documentation (expands to categories → sections with scroll-spy), Blog, Ecosystem, Releases, Donate. Navbar is just logo + social + theme toggle. Mobile: hamburger for sidebar, theme toggle far-right. `Link` component uses `next/link` for all internal routes; callers pass `variant="inline" | "heading" | "block" | "unstyled"` (the legacy `inline`/`unstyled` boolean props were removed).
+**Navigation:** Sidebar lives in `ClientLayout` (root layout) — persists across navigations via `SidebarFoldProvider` context. Search (DocSearch, module-level singleton) at top, then Home, Agents, Documentation (expands to categories → sections with scroll-spy), Blog, Ecosystem, Releases, Donate. Navbar is just logo + social + theme toggle. Mobile: hamburger for sidebar, theme toggle far-right. `Link` component uses `next/link` for internal routes and plain `<a>` for external URLs and static files (paths with file extensions like `/llms.txt`); callers pass `variant="inline" | "heading" | "block" | "unstyled"` (the legacy `inline`/`unstyled` boolean props were removed).
 
 **Homepage:** Two-column hero (copy left, live editor right) inside `LiveProvider`. Transparent background. Proof badges above CTA buttons. 10-year celebration effect (CSS bloom fireworks, respects reduced-motion). Company logos adapt via `brightness(0)` / `invert(1)`.
 
