{"owner":"cloudflare","repo":"cloudflare-docs","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["AGENTS.md"],"skills":{"AGENTS.md":"# AGENTS.md — Cloudflare Docs\n\nThis file helps AI agents understand the structure, tooling, and conventions of the `cloudflare-docs` repository so they can make correct, buildable changes.\n\n## Repository overview\n\nThis is the source for [developers.cloudflare.com](https://developers.cloudflare.com). It is an **Astro** site using the **Nimbus** (`nimbus-docs`) documentation framework. Content is authored in **MDX** (Markdown + JSX). The site is deployed as a Cloudflare Worker.\n\n- **Node.js**: 24.x\n- **Package manager**: pnpm (use `pnpm install --frozen-lockfile` to install)\n- **Primary branch**: `production` (not `main`)\n\n## Directory structure\n\n```\ncloudflare-docs/\n├── src/\n│   ├── content/\n│   │   ├── docs/           # 5,400+ MDX pages — the user-facing documentation\n│   │   ├── partials/       # 1,200+ reusable MDX snippets (by product)\n│   │   ├── changelog/      # Product changelogs (by product subdirectory)\n│   │   ├── glossary/       # Glossary term definitions (YAML)\n│   │   ├── products/       # Product metadata (YAML, 135 files)\n│   │   └── ...             # Other data collections (plans, fields, models, etc.)\n│   ├── components/         # Astro + React components (barrel: components.ts)\n│   ├── components.ts       # MDX component barrel — all MDX imports come from here\n│   ├── layouts/            # Page layout components\n│   ├── pages/              # Dynamic route pages (changelog, llms.txt, RSS, etc.)\n│   ├── schemas/            # Zod schemas for all content collections\n│   ├── plugins/            # Satteri hast pipeline plugins\n│   ├── scripts/            # Client-side scripts (analytics, mermaid, webmcp, etc.)\n│   ├── styles/             # CSS (Tailwind 4)\n│   ├── icons/              # Product SVG icons (~110)\n│   ├── assets/             # Processed images (optimized by Astro)\n│   ├── util/               # App utility functions\n│   └── content.config.ts   # Content collection definitions\n├── public/                 # Static files served as-is (images, redirects, robots.txt)\n├── worker/                 # Cloudflare Worker for serving the site\n├── bin/                    # Build scripts and CI helpers\n│   └── fetch-skills.ts     # Downloads skills.tar.gz from middlecache, extracts to skills/\n├── skills/                 # Agent Skills served at /.well-known/skills/ — GENERATED, do not edit\n│                           # Fetched from https://middlecache.ced.cloudflare.com/v1/cloudflare-skills/skills.tar.gz\n│                           # by bin/fetch-skills.ts, which runs automatically via prebuild/predev hooks.\n│                           # skills/ is in .gitignore and is NOT committed to the repository.\n├── .flue/                  # Flue cloudflare-docs-bot — see .flue/AGENTS.md\n├── astro.config.ts         # Astro + Nimbus configuration\n├── package.json\n└── tsconfig.json\n```\n\n## Content — writing and editing docs\n\n### File locations\n\n- Docs pages: `src/content/docs/{product}/`\n- Partials (reusable snippets): `src/content/partials/{product}/`\n- Images: `src/assets/images/{product}/`\n- Changelogs: `src/content/changelog/{product}/`\n\nEvery folder must have an `index.mdx`. Filenames must be lowercase with dashes between words.\n\n### Allowed file types in `src/content/`\n\nOnly `.mdx`, `.json`, `.yml`, `.yaml`, `.txt` files are allowed. The CI will reject anything else. Images must go in `src/assets/images/`, not in `src/content/`.\n\n### Frontmatter\n\nAll docs pages require frontmatter. Key fields:\n\n```yaml\n---\ntitle: Page Title # Required\ndescription: SEO meta description # Required when pcx_content_type is set\npcx_content_type: how-to # Page type (see below)\nsidebar:\n  order: 1 # Sort order in sidebar\n  label: Custom Label # Override sidebar text\nproducts: # References to src/content/directory/ entries\n  - workers\ndifficulty: Beginner # For tutorials: Beginner | Intermediate | Advanced\nreviewed: 2025-01-15 # YYYY-MM-DD of last content review\n---\n```\n\nValid `pcx_content_type` values: `changelog`, `concept`, `configuration`, `design-guide`, `example`, `faq`, `get-started`, `how-to`, `integration-guide`, `implementation-guide`, `learning-unit`, `navigation`, `overview`, `reference`, `reference-architecture`, `reference-architecture-diagram`, `release-notes`, `solution-guide`, `troubleshooting`, `tutorial`, `video`.\n\n### Writing and style rules\n\nFor MDX syntax, links, code blocks, formatting, and writing style, see `.agents/references/style-guide.md`. That file is the canonical agent reference — distilled from the full style guide at `src/content/docs/style-guide/`.\n\n## Components — major APIs\n\nComponents are imported from `~/components` in MDX files. Imports must appear after the frontmatter block — forgetting the import is a common mistake.\n\nFor full component documentation including props, examples, and mandatory usage rules, see `.agents/references/components.md`.\n\n## Validation — what to run after making changes\n\n> **CI note:** `pnpm run build` will time out in CI environments (GitHub Actions, etc. where `CI=true`). When running in CI, use `pnpm run check` and linters only — do **not** run a full build. The full build is only practical in local development environments.\n\n### Minimum validation for content changes (MDX edits)\n\n```bash\npnpm run check          # Type-check (validates frontmatter schemas + Astro types)\npnpm run build          # Full build (validates MDX parsing, image paths, internal links) — LOCAL ONLY, skip in CI\n```\n\n### Minimum validation for code changes (.ts/.tsx/.astro/.js)\n\n```bash\npnpm run check          # Type-check (Astro + Worker)\npnpm run lint           # ESLint\npnpm run format:core:check  # Prettier formatting check\npnpm run test           # Vitest (Workers, Node, and Astro suites)\n```\n\n### CI-only validation (when `CI=true`)\n\nUse this reduced set when running as a GitHub Action or in any CI environment:\n\n```bash\npnpm run check              # Type-check (validates frontmatter schemas + Astro types)\npnpm run lint               # ESLint\npnpm run format:core:check  # Prettier formatting check\n```\n\n### Full validation (matches CI pipeline, local only)\n\n```bash\npnpm run check              # Astro + Worker type checking\npnpm run lint               # ESLint\npnpm run format:core:check  # Prettier formatting check\npnpm run build              # Full build with link checking\npnpm run test               # All test suites\npnpm exec tsm bin/validate-redirects.ts  # Only if public/__redirects was modified\n```\n\n### Fixing formatting\n\nAfter editing any prettier-scoped file, run:\n\n```bash\npnpm run format             # Auto-fix all prettier-scoped files\n```\n\nAlways format edited files before committing — CI runs `pnpm run format:core:check` and will fail if formatting is off.\n\n### Syncing types after content collection changes\n\n```bash\npnpm run sync               # Regenerate Astro content collection types\n```\n\n## CI pipeline\n\nThe CI workflow (`.github/workflows/ci.yml`) runs on PRs to `production` and checks in order:\n\n1. File extension validation (only allowed types in `src/content/`)\n2. `pnpm run check` (Astro + Worker type checking)\n3. ESLint (reported inline on PR via reviewdog)\n4. `pnpm run format:core:check` (Prettier formatting)\n5. `pnpm run build` (full build + MDX parsing + image path validation)\n6. Redirect validation (`bin/validate-redirects.ts`)\n7. `pnpm run test` (all Vitest suites)\n\nA separate Semgrep workflow checks style guide compliance (dates, \"coming soon\" phrases) and produces warnings.\n\n## Common mistakes to avoid\n\n1. **Unescaped `{`, `}`, `<`, `>` in MDX prose** — the #1 build failure. Wrap in backticks or escape.\n2. **Forgetting component imports** — `<Details>`, `<Tabs>`, etc. must be imported from `~/components`.\n3. **Unsupported code block languages** — use `txt` for generic output, not `output` or `env`.\n4. **Capitalized language names** — use `json` not `JSON`, `javascript` not `JavaScript`.\n5. **Full URLs for internal links** — use `/workers/` not `https://developers.cloudflare.com/workers/`.\n6. **Relative file links** — `./page` is not supported. Use absolute paths from root.\n7. **Wrong image location** — images go in `src/assets/images/`, never in `src/content/`.\n8. **Skipping heading levels** — H2 then H4 without H3 will violate style guide rules.\n9. **`$` prefix in terminal commands** — the copy button copies verbatim, including the `$`.\n10. **Invalid changelog product folders** — the changelog folder name must match a `directory` entry id in `src/content/directory/`.\n11. **Redirect issues** — source URLs in `public/__redirects` must end in `/` (or `*`, `.xml`, `.json`, `.html`). No fragments in source URLs. No infinite loops.\n12. **Hand-crafted directory entry IDs** — never manually write `id` values in `src/content/directory/` files. Always run `node tools/directory-entry-ids --fix` to generate them.\n\n## Content collections\n\nThe site defines 19 content collections in `src/content.config.ts` with schemas in `src/schemas/`. The major ones:\n\n| Collection          | Location                         | Description                              |\n| ------------------- | -------------------------------- | ---------------------------------------- |\n| `docs`              | `src/content/docs/`              | Main documentation pages (MDX)           |\n| `partials`          | `src/content/partials/`          | Reusable content snippets (MDX)          |\n| `changelog`         | `src/content/changelog/`         | Product changelogs (MDX)                 |\n| `glossary`          | `src/content/glossary/`          | Glossary terms (YAML)                    |\n| `workers-ai-models` | `src/content/workers-ai-models/` | AI model definitions (JSON)              |\n| `directory`         | `src/content/directory/`         | Product/feature directory entries (YAML) |\n| `fields`            | `src/content/fields/`            | Ruleset engine field definitions (YAML)  |\n| `learning-paths`    | `src/content/learning-paths/`    | Learning path definitions (JSON)         |\n\n### Directory entry IDs\n\nEvery file in `src/content/directory/` **must** have a unique `id` field on the very first line. This is enforced by Semgrep rules in CI (`.semgrep/directory-entry-validation.yaml`).\n\n**Rules:**\n\n- The `id` must be exactly **6 characters** long.\n- Characters are drawn from a reduced-confusion set: `abcdefghijkmnopqrstuvwxyzACDEFGHJKLMNPQRTUVWXY34679`. This deliberately omits visually ambiguous characters (`l`/`1`/`I`, `O`/`0`, `B`/`8`, `S`/`5`, `Z`/`2`).\n- IDs are **randomly generated** — they must not contain human names or be hand-crafted.\n- The `id` is a **stable identifier** that stays with the YAML file even when the `name` or filename changes. Never modify an existing `id` unless fixing a validation error.\n- Files must use the `.yaml` extension, not `.yml`.\n\n**Generating IDs:**\n\nUse the `tools/directory-entry-ids` script to generate and validate IDs:\n\n```bash\nnode tools/directory-entry-ids        # Check all files, report errors\nnode tools/directory-entry-ids --fix  # Auto-fix missing, malformed, or duplicate IDs\n```\n\n**Do not** manually write `id` values. Always use the script to generate them.\n\n## Testing\n\nTests use Vitest with three workspace projects (`vitest.config.ts`):\n\n| Suite   | File pattern       | Runtime                           |\n| ------- | ------------------ | --------------------------------- |\n| Workers | `*.worker.test.ts` | `@cloudflare/vitest-pool-workers` |\n| Node    | `*.node.test.ts`   | Node.js                           |\n| Astro   | `*.astro.test.ts`  | Astro Vite config                 |\n\nRun all tests: `pnpm run test`\n\n## Web components\n\nNew web components in this codebase should use the `cfdocs-` prefix for custom element names (e.g., `<cfdocs-sheet>`, `<cfdocs-explain-code>`). This establishes a consistent naming pattern going forward.\n\n### Naming conventions\n\n- **Custom element names**: Use kebab-case with `cfdocs-` prefix (e.g., `cfdocs-sheet`)\n- **Class names**: Use PascalCase with `Element` suffix (e.g., `SheetElement`, `ExplainCodeElement`)\n- **File locations**: Place components in `src/components/{component-name}/` directories\n\n### Existing components\n\nExisting components (`warp-download`, `stream-player`, `rule-id`, `check-box`, `r2-local-uploads-diagram`, `animated-workflow-diagram`, `autoconfig-diagram`) are exempt from the `cfdocs-` prefix requirement and do not need to be renamed.\n\n## Flue cloudflare-docs-bot\n\nThe PR review bot for this repository lives in `.flue/`. It is a Cloudflare Worker (`cloudflare-docs-flue`) built with the Flue framework that reviews pull requests and posts structured feedback as GitHub comments.\n\n**If the bot is relevant to the task, read `.flue/AGENTS.md` first.** That file covers the worker architecture, workflow routing, specialist agents (code review, conventions, style-guide), R2 state management, local dev scripts, and deployment. All bot-related npm scripts are prefixed `flue:` in the root `package.json` (e.g. `pnpm run flue:dev`, `pnpm run flue:deploy`).\n\n## Agent skills, commands, and agents\n\nRepo-specific agent config lives in `.agents/`. All subdirectories are committed. Tool-specific paths (`.opencode/agents`, `CLAUDE.md`) are symlinks into `.agents/`.\n\n### Skills\n\nSkills live in `.agents/skills/`. Each skill's `SKILL.md` describes what it does and when to use it. Load a skill when the task matches its description.\n\nThe `contributing` skill is the entry point for any change to the docs — writing or editing pages, choosing content types and components, reviewing docs or code examples, adding changelog entries, and opening pull requests. It is a router that dispatches to task-specific files under `.agents/skills/contributing/references/`. Load it first for contribution tasks.\n\n### Agents\n\nCustom agent definitions live in `.agents/agents/` (symlinked from `.opencode/agents/`). Each agent's frontmatter describes its role.\n\n### Reference files\n\nShared reference files in `.agents/references/`:\n\n| File             | Contents                                                    |\n| ---------------- | ----------------------------------------------------------- |\n| `style-guide.md` | Canonical writing and formatting rules for all content work |\n| `components.md`  | Full MDX component catalog with props and usage examples    |\n| `procedures.md`  | Rules for writing step-by-step procedural instructions      |\n\n## Terminology and naming preferences\n\n- **Do not use \"PayGo\" in public-facing documentation.** Instead use the term **\"Free\"** when referring to standalone Free accounts that can be created from the dashboard.\n\n## Commit conventions\n\n- Format: `[Product] description` or `type: description`\n- Examples: `[Workers] Fix broken link in get-started`, `docs: clarify rate limiting behavior`, `fix: correct TypeScript example`\n- Common prefixes: `docs:`, `fix:`, `chore:`, `[Product]`\n"},"files":{"AGENTS.md":"# AGENTS.md — Cloudflare Docs\n\nThis file helps AI agents understand the structure, tooling, and conventions of the `cloudflare-docs` repository so they can make correct, buildable changes.\n\n## Repository overview\n\nThis is the source for [developers.cloudflare.com](https://developers.cloudflare.com). It is an **Astro** site using the **Nimbus** (`nimbus-docs`) documentation framework. Content is authored in **MDX** (Markdown + JSX). The site is deployed as a Cloudflare Worker.\n\n- **Node.js**: 24.x\n- **Package manager**: pnpm (use `pnpm install --frozen-lockfile` to install)\n- **Primary branch**: `production` (not `main`)\n\n## Directory structure\n\n```\ncloudflare-docs/\n├── src/\n│   ├── content/\n│   │   ├── docs/           # 5,400+ MDX pages — the user-facing documentation\n│   │   ├── partials/       # 1,200+ reusable MDX snippets (by product)\n│   │   ├── changelog/      # Product changelogs (by product subdirectory)\n│   │   ├── glossary/       # Glossary term definitions (YAML)\n│   │   ├── products/       # Product metadata (YAML, 135 files)\n│   │   └── ...             # Other data collections (plans, fields, models, etc.)\n│   ├── components/         # Astro + React components (barrel: components.ts)\n│   ├── components.ts       # MDX component barrel — all MDX imports come from here\n│   ├── layouts/            # Page layout components\n│   ├── pages/              # Dynamic route pages (changelog, llms.txt, RSS, etc.)\n│   ├── schemas/            # Zod schemas for all content collections\n│   ├── plugins/            # Satteri hast pipeline plugins\n│   ├── scripts/            # Client-side scripts (analytics, mermaid, webmcp, etc.)\n│   ├── styles/             # CSS (Tailwind 4)\n│   ├── icons/              # Product SVG icons (~110)\n│   ├── assets/             # Processed images (optimized by Astro)\n│   ├── util/               # App utility functions\n│   └── content.config.ts   # Content collection definitions\n├── public/                 # Static files served as-is (images, redirects, robots.txt)\n├── worker/                 # Cloudflare Worker for serving the site\n├── bin/                    # Build scripts and CI helpers\n│   └── fetch-skills.ts     # Downloads skills.tar.gz from middlecache, extracts to skills/\n├── skills/                 # Agent Skills served at /.well-known/skills/ — GENERATED, do not edit\n│                           # Fetched from https://middlecache.ced.cloudflare.com/v1/cloudflare-skills/skills.tar.gz\n│                           # by bin/fetch-skills.ts, which runs automatically via prebuild/predev hooks.\n│                           # skills/ is in .gitignore and is NOT committed to the repository.\n├── .flue/                  # Flue cloudflare-docs-bot — see .flue/AGENTS.md\n├── astro.config.ts         # Astro + Nimbus configuration\n├── package.json\n└── tsconfig.json\n```\n\n## Content — writing and editing docs\n\n### File locations\n\n- Docs pages: `src/content/docs/{product}/`\n- Partials (reusable snippets): `src/content/partials/{product}/`\n- Images: `src/assets/images/{product}/`\n- Changelogs: `src/content/changelog/{product}/`\n\nEvery folder must have an `index.mdx`. Filenames must be lowercase with dashes between words.\n\n### Allowed file types in `src/content/`\n\nOnly `.mdx`, `.json`, `.yml`, `.yaml`, `.txt` files are allowed. The CI will reject anything else. Images must go in `src/assets/images/`, not in `src/content/`.\n\n### Frontmatter\n\nAll docs pages require frontmatter. Key fields:\n\n```yaml\n---\ntitle: Page Title # Required\ndescription: SEO meta description # Required when pcx_content_type is set\npcx_content_type: how-to # Page type (see below)\nsidebar:\n  order: 1 # Sort order in sidebar\n  label: Custom Label # Override sidebar text\nproducts: # References to src/content/directory/ entries\n  - workers\ndifficulty: Beginner # For tutorials: Beginner | Intermediate | Advanced\nreviewed: 2025-01-15 # YYYY-MM-DD of last content review\n---\n```\n\nValid `pcx_content_type` values: `changelog`, `concept`, `configuration`, `design-guide`, `example`, `faq`, `get-started`, `how-to`, `integration-guide`, `implementation-guide`, `learning-unit`, `navigation`, `overview`, `reference`, `reference-architecture`, `reference-architecture-diagram`, `release-notes`, `solution-guide`, `troubleshooting`, `tutorial`, `video`.\n\n### Writing and style rules\n\nFor MDX syntax, links, code blocks, formatting, and writing style, see `.agents/references/style-guide.md`. That file is the canonical agent reference — distilled from the full style guide at `src/content/docs/style-guide/`.\n\n## Components — major APIs\n\nComponents are imported from `~/components` in MDX files. Imports must appear after the frontmatter block — forgetting the import is a common mistake.\n\nFor full component documentation including props, examples, and mandatory usage rules, see `.agents/references/components.md`.\n\n## Validation — what to run after making changes\n\n> **CI note:** `pnpm run build` will time out in CI environments (GitHub Actions, etc. where `CI=true`). When running in CI, use `pnpm run check` and linters only — do **not** run a full build. The full build is only practical in local development environments.\n\n### Minimum validation for content changes (MDX edits)\n\n```bash\npnpm run check          # Type-check (validates frontmatter schemas + Astro types)\npnpm run build          # Full build (validates MDX parsing, image paths, internal links) — LOCAL ONLY, skip in CI\n```\n\n### Minimum validation for code changes (.ts/.tsx/.astro/.js)\n\n```bash\npnpm run check          # Type-check (Astro + Worker)\npnpm run lint           # ESLint\npnpm run format:core:check  # Prettier formatting check\npnpm run test           # Vitest (Workers, Node, and Astro suites)\n```\n\n### CI-only validation (when `CI=true`)\n\nUse this reduced set when running as a GitHub Action or in any CI environment:\n\n```bash\npnpm run check              # Type-check (validates frontmatter schemas + Astro types)\npnpm run lint               # ESLint\npnpm run format:core:check  # Prettier formatting check\n```\n\n### Full validation (matches CI pipeline, local only)\n\n```bash\npnpm run check              # Astro + Worker type checking\npnpm run lint               # ESLint\npnpm run format:core:check  # Prettier formatting check\npnpm run build              # Full build with link checking\npnpm run test               # All test suites\npnpm exec tsm bin/validate-redirects.ts  # Only if public/__redirects was modified\n```\n\n### Fixing formatting\n\nAfter editing any prettier-scoped file, run:\n\n```bash\npnpm run format             # Auto-fix all prettier-scoped files\n```\n\nAlways format edited files before committing — CI runs `pnpm run format:core:check` and will fail if formatting is off.\n\n### Syncing types after content collection changes\n\n```bash\npnpm run sync               # Regenerate Astro content collection types\n```\n\n## CI pipeline\n\nThe CI workflow (`.github/workflows/ci.yml`) runs on PRs to `production` and checks in order:\n\n1. File extension validation (only allowed types in `src/content/`)\n2. `pnpm run check` (Astro + Worker type checking)\n3. ESLint (reported inline on PR via reviewdog)\n4. `pnpm run format:core:check` (Prettier formatting)\n5. `pnpm run build` (full build + MDX parsing + image path validation)\n6. Redirect validation (`bin/validate-redirects.ts`)\n7. `pnpm run test` (all Vitest suites)\n\nA separate Semgrep workflow checks style guide compliance (dates, \"coming soon\" phrases) and produces warnings.\n\n## Common mistakes to avoid\n\n1. **Unescaped `{`, `}`, `<`, `>` in MDX prose** — the #1 build failure. Wrap in backticks or escape.\n2. **Forgetting component imports** — `<Details>`, `<Tabs>`, etc. must be imported from `~/components`.\n3. **Unsupported code block languages** — use `txt` for generic output, not `output` or `env`.\n4. **Capitalized language names** — use `json` not `JSON`, `javascript` not `JavaScript`.\n5. **Full URLs for internal links** — use `/workers/` not `https://developers.cloudflare.com/workers/`.\n6. **Relative file links** — `./page` is not supported. Use absolute paths from root.\n7. **Wrong image location** — images go in `src/assets/images/`, never in `src/content/`.\n8. **Skipping heading levels** — H2 then H4 without H3 will violate style guide rules.\n9. **`$` prefix in terminal commands** — the copy button copies verbatim, including the `$`.\n10. **Invalid changelog product folders** — the changelog folder name must match a `directory` entry id in `src/content/directory/`.\n11. **Redirect issues** — source URLs in `public/__redirects` must end in `/` (or `*`, `.xml`, `.json`, `.html`). No fragments in source URLs. No infinite loops.\n12. **Hand-crafted directory entry IDs** — never manually write `id` values in `src/content/directory/` files. Always run `node tools/directory-entry-ids --fix` to generate them.\n\n## Content collections\n\nThe site defines 19 content collections in `src/content.config.ts` with schemas in `src/schemas/`. The major ones:\n\n| Collection          | Location                         | Description                              |\n| ------------------- | -------------------------------- | ---------------------------------------- |\n| `docs`              | `src/content/docs/`              | Main documentation pages (MDX)           |\n| `partials`          | `src/content/partials/`          | Reusable content snippets (MDX)          |\n| `changelog`         | `src/content/changelog/`         | Product changelogs (MDX)                 |\n| `glossary`          | `src/content/glossary/`          | Glossary terms (YAML)                    |\n| `workers-ai-models` | `src/content/workers-ai-models/` | AI model definitions (JSON)              |\n| `directory`         | `src/content/directory/`         | Product/feature directory entries (YAML) |\n| `fields`            | `src/content/fields/`            | Ruleset engine field definitions (YAML)  |\n| `learning-paths`    | `src/content/learning-paths/`    | Learning path definitions (JSON)         |\n\n### Directory entry IDs\n\nEvery file in `src/content/directory/` **must** have a unique `id` field on the very first line. This is enforced by Semgrep rules in CI (`.semgrep/directory-entry-validation.yaml`).\n\n**Rules:**\n\n- The `id` must be exactly **6 characters** long.\n- Characters are drawn from a reduced-confusion set: `abcdefghijkmnopqrstuvwxyzACDEFGHJKLMNPQRTUVWXY34679`. This deliberately omits visually ambiguous characters (`l`/`1`/`I`, `O`/`0`, `B`/`8`, `S`/`5`, `Z`/`2`).\n- IDs are **randomly generated** — they must not contain human names or be hand-crafted.\n- The `id` is a **stable identifier** that stays with the YAML file even when the `name` or filename changes. Never modify an existing `id` unless fixing a validation error.\n- Files must use the `.yaml` extension, not `.yml`.\n\n**Generating IDs:**\n\nUse the `tools/directory-entry-ids` script to generate and validate IDs:\n\n```bash\nnode tools/directory-entry-ids        # Check all files, report errors\nnode tools/directory-entry-ids --fix  # Auto-fix missing, malformed, or duplicate IDs\n```\n\n**Do not** manually write `id` values. Always use the script to generate them.\n\n## Testing\n\nTests use Vitest with three workspace projects (`vitest.config.ts`):\n\n| Suite   | File pattern       | Runtime                           |\n| ------- | ------------------ | --------------------------------- |\n| Workers | `*.worker.test.ts` | `@cloudflare/vitest-pool-workers` |\n| Node    | `*.node.test.ts`   | Node.js                           |\n| Astro   | `*.astro.test.ts`  | Astro Vite config                 |\n\nRun all tests: `pnpm run test`\n\n## Web components\n\nNew web components in this codebase should use the `cfdocs-` prefix for custom element names (e.g., `<cfdocs-sheet>`, `<cfdocs-explain-code>`). This establishes a consistent naming pattern going forward.\n\n### Naming conventions\n\n- **Custom element names**: Use kebab-case with `cfdocs-` prefix (e.g., `cfdocs-sheet`)\n- **Class names**: Use PascalCase with `Element` suffix (e.g., `SheetElement`, `ExplainCodeElement`)\n- **File locations**: Place components in `src/components/{component-name}/` directories\n\n### Existing components\n\nExisting components (`warp-download`, `stream-player`, `rule-id`, `check-box`, `r2-local-uploads-diagram`, `animated-workflow-diagram`, `autoconfig-diagram`) are exempt from the `cfdocs-` prefix requirement and do not need to be renamed.\n\n## Flue cloudflare-docs-bot\n\nThe PR review bot for this repository lives in `.flue/`. It is a Cloudflare Worker (`cloudflare-docs-flue`) built with the Flue framework that reviews pull requests and posts structured feedback as GitHub comments.\n\n**If the bot is relevant to the task, read `.flue/AGENTS.md` first.** That file covers the worker architecture, workflow routing, specialist agents (code review, conventions, style-guide), R2 state management, local dev scripts, and deployment. All bot-related npm scripts are prefixed `flue:` in the root `package.json` (e.g. `pnpm run flue:dev`, `pnpm run flue:deploy`).\n\n## Agent skills, commands, and agents\n\nRepo-specific agent config lives in `.agents/`. All subdirectories are committed. Tool-specific paths (`.opencode/agents`, `CLAUDE.md`) are symlinks into `.agents/`.\n\n### Skills\n\nSkills live in `.agents/skills/`. Each skill's `SKILL.md` describes what it does and when to use it. Load a skill when the task matches its description.\n\nThe `contributing` skill is the entry point for any change to the docs — writing or editing pages, choosing content types and components, reviewing docs or code examples, adding changelog entries, and opening pull requests. It is a router that dispatches to task-specific files under `.agents/skills/contributing/references/`. Load it first for contribution tasks.\n\n### Agents\n\nCustom agent definitions live in `.agents/agents/` (symlinked from `.opencode/agents/`). Each agent's frontmatter describes its role.\n\n### Reference files\n\nShared reference files in `.agents/references/`:\n\n| File             | Contents                                                    |\n| ---------------- | ----------------------------------------------------------- |\n| `style-guide.md` | Canonical writing and formatting rules for all content work |\n| `components.md`  | Full MDX component catalog with props and usage examples    |\n| `procedures.md`  | Rules for writing step-by-step procedural instructions      |\n\n## Terminology and naming preferences\n\n- **Do not use \"PayGo\" in public-facing documentation.** Instead use the term **\"Free\"** when referring to standalone Free accounts that can be created from the dashboard.\n\n## Commit conventions\n\n- Format: `[Product] description` or `type: description`\n- Examples: `[Workers] Fix broken link in get-started`, `docs: clarify rate limiting behavior`, `fix: correct TypeScript example`\n- Common prefixes: `docs:`, `fix:`, `chore:`, `[Product]`\n"},"items":[{"name":"AGENTS.md","path":"AGENTS.md","title":"AGENTS.md","content":"# AGENTS.md — Cloudflare Docs\n\nThis file helps AI agents understand the structure, tooling, and conventions of the `cloudflare-docs` repository so they can make correct, buildable changes.\n\n## Repository overview\n\nThis is the source for [developers.cloudflare.com](https://developers.cloudflare.com). It is an **Astro** site using the **Nimbus** (`nimbus-docs`) documentation framework. Content is authored in **MDX** (Markdown + JSX). The site is deployed as a Cloudflare Worker.\n\n- **Node.js**: 24.x\n- **Package manager**: pnpm (use `pnpm install --frozen-lockfile` to install)\n- **Primary branch**: `production` (not `main`)\n\n## Directory structure\n\n```\ncloudflare-docs/\n├── src/\n│   ├── content/\n│   │   ├── docs/           # 5,400+ MDX pages — the user-facing documentation\n│   │   ├── partials/       # 1,200+ reusable MDX snippets (by product)\n│   │   ├── changelog/      # Product changelogs (by product subdirectory)\n│   │   ├── glossary/       # Glossary term definitions (YAML)\n│   │   ├── products/       # Product metadata (YAML, 135 files)\n│   │   └── ...             # Other data collections (plans, fields, models, etc.)\n│   ├── components/         # Astro + React components (barrel: components.ts)\n│   ├── components.ts       # MDX component barrel — all MDX imports come from here\n│   ├── layouts/            # Page layout components\n│   ├── pages/              # Dynamic route pages (changelog, llms.txt, RSS, etc.)\n│   ├── schemas/            # Zod schemas for all content collections\n│   ├── plugins/            # Satteri hast pipeline plugins\n│   ├── scripts/            # Client-side scripts (analytics, mermaid, webmcp, etc.)\n│   ├── styles/             # CSS (Tailwind 4)\n│   ├── icons/              # Product SVG icons (~110)\n│   ├── assets/             # Processed images (optimized by Astro)\n│   ├── util/               # App utility functions\n│   └── content.config.ts   # Content collection definitions\n├── public/                 # Static files served as-is (images, redirects, robots.txt)\n├── worker/                 # Cloudflare Worker for serving the site\n├── bin/                    # Build scripts and CI helpers\n│   └── fetch-skills.ts     # Downloads skills.tar.gz from middlecache, extracts to skills/\n├── skills/                 # Agent Skills served at /.well-known/skills/ — GENERATED, do not edit\n│                           # Fetched from https://middlecache.ced.cloudflare.com/v1/cloudflare-skills/skills.tar.gz\n│                           # by bin/fetch-skills.ts, which runs automatically via prebuild/predev hooks.\n│                           # skills/ is in .gitignore and is NOT committed to the repository.\n├── .flue/                  # Flue cloudflare-docs-bot — see .flue/AGENTS.md\n├── astro.config.ts         # Astro + Nimbus configuration\n├── package.json\n└── tsconfig.json\n```\n\n## Content — writing and editing docs\n\n### File locations\n\n- Docs pages: `src/content/docs/{product}/`\n- Partials (reusable snippets): `src/content/partials/{product}/`\n- Images: `src/assets/images/{product}/`\n- Changelogs: `src/content/changelog/{product}/`\n\nEvery folder must have an `index.mdx`. Filenames must be lowercase with dashes between words.\n\n### Allowed file types in `src/content/`\n\nOnly `.mdx`, `.json`, `.yml`, `.yaml`, `.txt` files are allowed. The CI will reject anything else. Images must go in `src/assets/images/`, not in `src/content/`.\n\n### Frontmatter\n\nAll docs pages require frontmatter. Key fields:\n\n```yaml\n---\ntitle: Page Title # Required\ndescription: SEO meta description # Required when pcx_content_type is set\npcx_content_type: how-to # Page type (see below)\nsidebar:\n  order: 1 # Sort order in sidebar\n  label: Custom Label # Override sidebar text\nproducts: # References to src/content/directory/ entries\n  - workers\ndifficulty: Beginner # For tutorials: Beginner | Intermediate | Advanced\nreviewed: 2025-01-15 # YYYY-MM-DD of last content review\n---\n```\n\nValid `pcx_content_type` values: `changelog`, `concept`, `configuration`, `design-guide`, `example`, `faq`, `get-started`, `how-to`, `integration-guide`, `implementation-guide`, `learning-unit`, `navigation`, `overview`, `reference`, `reference-architecture`, `reference-architecture-diagram`, `release-notes`, `solution-guide`, `troubleshooting`, `tutorial`, `video`.\n\n### Writing and style rules\n\nFor MDX syntax, links, code blocks, formatting, and writing style, see `.agents/references/style-guide.md`. That file is the canonical agent reference — distilled from the full style guide at `src/content/docs/style-guide/`.\n\n## Components — major APIs\n\nComponents are imported from `~/components` in MDX files. Imports must appear after the frontmatter block — forgetting the import is a common mistake.\n\nFor full component documentation including props, examples, and mandatory usage rules, see `.agents/references/components.md`.\n\n## Validation — what to run after making changes\n\n> **CI note:** `pnpm run build` will time out in CI environments (GitHub Actions, etc. where `CI=true`). When running in CI, use `pnpm run check` and linters only — do **not** run a full build. The full build is only practical in local development environments.\n\n### Minimum validation for content changes (MDX edits)\n\n```bash\npnpm run check          # Type-check (validates frontmatter schemas + Astro types)\npnpm run build          # Full build (validates MDX parsing, image paths, internal links) — LOCAL ONLY, skip in CI\n```\n\n### Minimum validation for code changes (.ts/.tsx/.astro/.js)\n\n```bash\npnpm run check          # Type-check (Astro + Worker)\npnpm run lint           # ESLint\npnpm run format:core:check  # Prettier formatting check\npnpm run test           # Vitest (Workers, Node, and Astro suites)\n```\n\n### CI-only validation (when `CI=true`)\n\nUse this reduced set when running as a GitHub Action or in any CI environment:\n\n```bash\npnpm run check              # Type-check (validates frontmatter schemas + Astro types)\npnpm run lint               # ESLint\npnpm run format:core:check  # Prettier formatting check\n```\n\n### Full validation (matches CI pipeline, local only)\n\n```bash\npnpm run check              # Astro + Worker type checking\npnpm run lint               # ESLint\npnpm run format:core:check  # Prettier formatting check\npnpm run build              # Full build with link checking\npnpm run test               # All test suites\npnpm exec tsm bin/validate-redirects.ts  # Only if public/__redirects was modified\n```\n\n### Fixing formatting\n\nAfter editing any prettier-scoped file, run:\n\n```bash\npnpm run format             # Auto-fix all prettier-scoped files\n```\n\nAlways format edited files before committing — CI runs `pnpm run format:core:check` and will fail if formatting is off.\n\n### Syncing types after content collection changes\n\n```bash\npnpm run sync               # Regenerate Astro content collection types\n```\n\n## CI pipeline\n\nThe CI workflow (`.github/workflows/ci.yml`) runs on PRs to `production` and checks in order:\n\n1. File extension validation (only allowed types in `src/content/`)\n2. `pnpm run check` (Astro + Worker type checking)\n3. ESLint (reported inline on PR via reviewdog)\n4. `pnpm run format:core:check` (Prettier formatting)\n5. `pnpm run build` (full build + MDX parsing + image path validation)\n6. Redirect validation (`bin/validate-redirects.ts`)\n7. `pnpm run test` (all Vitest suites)\n\nA separate Semgrep workflow checks style guide compliance (dates, \"coming soon\" phrases) and produces warnings.\n\n## Common mistakes to avoid\n\n1. **Unescaped `{`, `}`, `<`, `>` in MDX prose** — the #1 build failure. Wrap in backticks or escape.\n2. **Forgetting component imports** — `<Details>`, `<Tabs>`, etc. must be imported from `~/components`.\n3. **Unsupported code block languages** — use `txt` for generic output, not `output` or `env`.\n4. **Capitalized language names** — use `json` not `JSON`, `javascript` not `JavaScript`.\n5. **Full URLs for internal links** — use `/workers/` not `https://developers.cloudflare.com/workers/`.\n6. **Relative file links** — `./page` is not supported. Use absolute paths from root.\n7. **Wrong image location** — images go in `src/assets/images/`, never in `src/content/`.\n8. **Skipping heading levels** — H2 then H4 without H3 will violate style guide rules.\n9. **`$` prefix in terminal commands** — the copy button copies verbatim, including the `$`.\n10. **Invalid changelog product folders** — the changelog folder name must match a `directory` entry id in `src/content/directory/`.\n11. **Redirect issues** — source URLs in `public/__redirects` must end in `/` (or `*`, `.xml`, `.json`, `.html`). No fragments in source URLs. No infinite loops.\n12. **Hand-crafted directory entry IDs** — never manually write `id` values in `src/content/directory/` files. Always run `node tools/directory-entry-ids --fix` to generate them.\n\n## Content collections\n\nThe site defines 19 content collections in `src/content.config.ts` with schemas in `src/schemas/`. The major ones:\n\n| Collection          | Location                         | Description                              |\n| ------------------- | -------------------------------- | ---------------------------------------- |\n| `docs`              | `src/content/docs/`              | Main documentation pages (MDX)           |\n| `partials`          | `src/content/partials/`          | Reusable content snippets (MDX)          |\n| `changelog`         | `src/content/changelog/`         | Product changelogs (MDX)                 |\n| `glossary`          | `src/content/glossary/`          | Glossary terms (YAML)                    |\n| `workers-ai-models` | `src/content/workers-ai-models/` | AI model definitions (JSON)              |\n| `directory`         | `src/content/directory/`         | Product/feature directory entries (YAML) |\n| `fields`            | `src/content/fields/`            | Ruleset engine field definitions (YAML)  |\n| `learning-paths`    | `src/content/learning-paths/`    | Learning path definitions (JSON)         |\n\n### Directory entry IDs\n\nEvery file in `src/content/directory/` **must** have a unique `id` field on the very first line. This is enforced by Semgrep rules in CI (`.semgrep/directory-entry-validation.yaml`).\n\n**Rules:**\n\n- The `id` must be exactly **6 characters** long.\n- Characters are drawn from a reduced-confusion set: `abcdefghijkmnopqrstuvwxyzACDEFGHJKLMNPQRTUVWXY34679`. This deliberately omits visually ambiguous characters (`l`/`1`/`I`, `O`/`0`, `B`/`8`, `S`/`5`, `Z`/`2`).\n- IDs are **randomly generated** — they must not contain human names or be hand-crafted.\n- The `id` is a **stable identifier** that stays with the YAML file even when the `name` or filename changes. Never modify an existing `id` unless fixing a validation error.\n- Files must use the `.yaml` extension, not `.yml`.\n\n**Generating IDs:**\n\nUse the `tools/directory-entry-ids` script to generate and validate IDs:\n\n```bash\nnode tools/directory-entry-ids        # Check all files, report errors\nnode tools/directory-entry-ids --fix  # Auto-fix missing, malformed, or duplicate IDs\n```\n\n**Do not** manually write `id` values. Always use the script to generate them.\n\n## Testing\n\nTests use Vitest with three workspace projects (`vitest.config.ts`):\n\n| Suite   | File pattern       | Runtime                           |\n| ------- | ------------------ | --------------------------------- |\n| Workers | `*.worker.test.ts` | `@cloudflare/vitest-pool-workers` |\n| Node    | `*.node.test.ts`   | Node.js                           |\n| Astro   | `*.astro.test.ts`  | Astro Vite config                 |\n\nRun all tests: `pnpm run test`\n\n## Web components\n\nNew web components in this codebase should use the `cfdocs-` prefix for custom element names (e.g., `<cfdocs-sheet>`, `<cfdocs-explain-code>`). This establishes a consistent naming pattern going forward.\n\n### Naming conventions\n\n- **Custom element names**: Use kebab-case with `cfdocs-` prefix (e.g., `cfdocs-sheet`)\n- **Class names**: Use PascalCase with `Element` suffix (e.g., `SheetElement`, `ExplainCodeElement`)\n- **File locations**: Place components in `src/components/{component-name}/` directories\n\n### Existing components\n\nExisting components (`warp-download`, `stream-player`, `rule-id`, `check-box`, `r2-local-uploads-diagram`, `animated-workflow-diagram`, `autoconfig-diagram`) are exempt from the `cfdocs-` prefix requirement and do not need to be renamed.\n\n## Flue cloudflare-docs-bot\n\nThe PR review bot for this repository lives in `.flue/`. It is a Cloudflare Worker (`cloudflare-docs-flue`) built with the Flue framework that reviews pull requests and posts structured feedback as GitHub comments.\n\n**If the bot is relevant to the task, read `.flue/AGENTS.md` first.** That file covers the worker architecture, workflow routing, specialist agents (code review, conventions, style-guide), R2 state management, local dev scripts, and deployment. All bot-related npm scripts are prefixed `flue:` in the root `package.json` (e.g. `pnpm run flue:dev`, `pnpm run flue:deploy`).\n\n## Agent skills, commands, and agents\n\nRepo-specific agent config lives in `.agents/`. All subdirectories are committed. Tool-specific paths (`.opencode/agents`, `CLAUDE.md`) are symlinks into `.agents/`.\n\n### Skills\n\nSkills live in `.agents/skills/`. Each skill's `SKILL.md` describes what it does and when to use it. Load a skill when the task matches its description.\n\nThe `contributing` skill is the entry point for any change to the docs — writing or editing pages, choosing content types and components, reviewing docs or code examples, adding changelog entries, and opening pull requests. It is a router that dispatches to task-specific files under `.agents/skills/contributing/references/`. Load it first for contribution tasks.\n\n### Agents\n\nCustom agent definitions live in `.agents/agents/` (symlinked from `.opencode/agents/`). Each agent's frontmatter describes its role.\n\n### Reference files\n\nShared reference files in `.agents/references/`:\n\n| File             | Contents                                                    |\n| ---------------- | ----------------------------------------------------------- |\n| `style-guide.md` | Canonical writing and formatting rules for all content work |\n| `components.md`  | Full MDX component catalog with props and usage examples    |\n| `procedures.md`  | Rules for writing step-by-step procedural instructions      |\n\n## Terminology and naming preferences\n\n- **Do not use \"PayGo\" in public-facing documentation.** Instead use the term **\"Free\"** when referring to standalone Free accounts that can be created from the dashboard.\n\n## Commit conventions\n\n- Format: `[Product] description` or `type: description`\n- Examples: `[Workers] Fix broken link in get-started`, `docs: clarify rate limiting behavior`, `fix: correct TypeScript example`\n- Common prefixes: `docs:`, `fix:`, `chore:`, `[Product]`\n","category":"root","tokens":3711}]}