> ## Documentation Index
> Fetch the complete documentation index at: https://developers.kit.com/llms.txt
> Use this file to discover all available pages before exploring further.

# CLAUDE

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Overview

This is the Kit Developer Documentation site at [https://developers.kit.com/](https://developers.kit.com/), built with [Mintlify](https://mintlify.com/docs). Content is written in MDX (Markdown + JSX). Changes merged to `main` are automatically deployed by Mintlify.

## Git Workflow

Always create a new branch for changes — never commit directly to `main`. Merging to `main` triggers an automatic deployment to [https://developers.kit.com/](https://developers.kit.com/).

## Mintlify Reference

Mintlify provides LLM-friendly documentation:

* Summary: [https://www.mintlify.com/docs/llms.txt](https://www.mintlify.com/docs/llms.txt)
* Full: [https://www.mintlify.com/docs/llms-full.txt](https://www.mintlify.com/docs/llms-full.txt)

## Local Development

```bash theme={null}
# Install Mintlify CLI (requires Node 19+)
npm i -g mintlify

# Run local dev server
npx mint dev

# Check for broken links
mintlify broken-links
```

## Architecture

**`docs.json`** — The central config file controlling all navigation, theming, fonts, API settings, and metadata. All new pages must be registered here under `navigation.tabs` to appear in the sidebar.

**Content areas:**

* `welcome.mdx` — Landing page
* `kit-app-store/` — Kit App Store integration docs (OAuth, app config, versioning, best practices)
* `plugins/` — Plugin development docs including component library, content blocks, media sources, automation nodes
* `api-reference/` — API v4 (current, powered by `api-reference/v4.json` OpenAPI spec) and v3 (legacy, individual MDX files)
* `changelog.mdx` — Public developer changelog using Mintlify `<Update>` components
* `snippets/` — Reusable code examples

**`api-reference/v4.json`** — OpenAPI 3.0 spec for current API. API reference pages are auto-generated from this file; endpoint pages don't need hand-authored MDX.

## Changelog Entries

The changelog uses Mintlify's `<Update>` component format. When adding entries manually, follow this structure from `.github/prompts/changelog.md`:

```xml theme={null}
<Update label="February 2026" tags={["API"]}>
## 🚀 Feature title
One or two sentences describing what developers can now do.
</Update>
```

Emoji conventions: 🚀 Added, 🔧 Changed, 🐛 Fixed, ⚠️ Breaking Changes

Valid tags: `"API"`, `"Kit App Store"`, `"Plugins"`, `"Webhooks"`, `"SDK"`, `"Authentication"`, `"Documentation"`, `"Forms"`, `"Automation"`, `"Commerce"`, `"Analytics"`

There is also an automated changelog pipeline via `.github/workflows/process-shipped-message.yml` that generates entries from Slack using OpenAI.

## Adding New Pages

1. Create the `.mdx` file in the appropriate directory.
2. Register the page path in `docs.json` under the correct tab/group in `navigation.tabs`.

## API Documentation

API v4 is spec-driven — update `api-reference/v4.json` to add/modify endpoints. API v3 pages are hand-authored MDX in `api-reference/v3/`.

### Per-operation prose in v4.json

Add per-endpoint prose via the `description` field on each operation (sibling of `summary`). Reference example: `paths./v4/broadcasts.post.description`.

Mintlify's OpenAPI `description` renderer is markdown-flavoured but stripped down — only inline elements survive:

* **Works:** paragraphs (`\n\n` or `<br/><br/>`), backticked code, `**bold**`, `[links](/path)`
* **Stripped silently:** markdown bullet lists (`\n- item`), blockquotes (`> ...`), headings, `<ul>` / `<li>`, Mintlify components (`<Note>`, `<Tip>`, `<Warning>`)
* **Renders but unstyled:** `<aside class='notice'>` — passes through as a bare `<aside>` element with no callout CSS

Reshape lists into prose; for callouts use a bold lead-in (`**Note:** …`) rather than a component.

`npx mint dev` does **not** hot-reload `v4.json` — restart the dev server after spec edits.