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

# AGENTS

# AGENTS.md

Entry point for AI coding agents working on the Extension.js documentation site.

## What this repo is

The source for [extension.js.org](https://extension.js.org), the documentation site for [Extension.js](https://github.com/extension-js/extension.js), a cross-browser extension framework. Built with [Mintlify](https://mintlify.com).

## Layout

```
extension.js.org/
├── docs.json              # Site config (navigation, theme, integrations)
├── docs/                  # All documentation pages (MDX)
│   ├── getting-started/
│   ├── concepts/
│   ├── features/
│   ├── workflows/
│   ├── commands/
│   ├── browsers/
│   ├── languages-and-frameworks/
│   ├── integrations/
│   ├── implementation-guide/
│   └── ai-access.mdx      # MCP and llms.txt entry points
├── blog/                  # Blog posts
├── snippets/              # Reusable MDX components
├── images/                # Static assets referenced as /images/...
├── index.mdx              # Site landing page
├── style.css              # Custom styling on top of Mintlify theme
├── robots.txt
└── .agents/skills/        # Skill files for agents (mintlify, mintlify-api, mintlify-docs)
```

## Commands

```sh theme={null}
pnpm install        # Install dependencies (Node >= 22.18.0, pnpm 10)
pnpm dev            # Local preview at localhost:3000
pnpm build          # Build the site (mint build)
pnpm broken-links   # Check internal links
pnpm validate       # Validate the docs build
pnpm check          # lint + format + spellcheck
pnpm test           # Run vitest tests
```

Always run `pnpm check` before opening a PR.

## Conventions

* **Page format:** MDX with YAML frontmatter. `title` is required, `description` is strongly recommended for SEO.
* **Filenames:** kebab-case (`getting-started.mdx`, `manifest-v3.mdx`).
* **Internal links:** root-relative without extension (`/concepts/manifest`, never `../concepts/manifest.mdx`).
* **Images:** store in `/images`, reference as `/images/example.png`.
* **Navigation:** every new page must be registered in `docs.json` or it will be hidden.
* **Voice:** second person, active voice, sentence-case headings. No marketing language ("powerful", "seamless"), no filler ("in order to", "it's important to note").
* **Punctuation:** no em dashes. Use commas, colons, or parentheses.
* **Verbs:** prefer "choose" over "pick" or "select" for selection/option language (see commit history for prior standardizations).
* **Code blocks:** always tag with a language.

## AI access surfaces

The site exposes two AI-accessible endpoints, documented in `docs/ai-access.mdx`:

* **MCP server:** `https://extensionjs.mintlify.app/mcp` (full search and page-fetch tools)
* **llms.txt:** `/llms.txt` (index) and `/llms-full.txt` (full bundle), auto-generated by Mintlify on every deploy

When pointing other agents at this docs site for grounded answers, prefer the MCP server.

## Skills available

`.agents/skills/` contains reusable skill files for agents working on the site:

* `mintlify/SKILL.md`: writing docs, components, navigation, deployment
* `mintlify-api/SKILL.md`: programmatic deployment and metadata via REST API
* `mintlify-docs/SKILL.md`: Mintlify-specific documentation patterns

Load these when working on related tasks rather than guessing Mintlify behavior.

## Workflow for changes

1. Read `docs.json` to understand navigation structure.
2. Search existing pages before creating new ones, prefer updates and links over duplication.
3. Read 2-3 nearby pages to match tone and structure.
4. Write content, update `docs.json` if a new page is added.
5. Run `pnpm check`, `pnpm broken-links`, `pnpm validate`.
6. Commit with a conventional prefix (`docs:`, `fix:`, `feat:`). Do not include AI co-author trailers.

## What not to do

* Do not introduce a hand-rolled `index.mdx` redesign without flagging the brand gap first, the current landing page is intentional.
* Do not rename `docs.json` to `mint.json`, `mint.json` is deprecated.
* Do not add files to the root `docs/` folder without a navigation entry.
* Do not use relative paths or file extensions in internal links.