# AI Coding Agents

Zuplo ships version-matched documentation inside the `zuplo` npm package,
allowing AI coding agents to reference accurate, up-to-date APIs and patterns.
An `AGENTS.md` file at the root of your project directs agents to these bundled
docs instead of their training data.

For task-specific playbooks and Zuplo capabilities beyond documentation lookup,
see:

- [Agent Skills](../build-with-ai/skills.md) — install the official skills from
  [`zuplo/tools`](https://github.com/zuplo/tools).
- [Docs MCP Server](../build-with-ai/docs-mcp-server.md) — real-time search and
  Q&A across the full Zuplo documentation.
- [Zuplo MCP Server](../build-with-ai/zuplo-mcp-server.md) — manage your Zuplo
  account programmatically from agents.

## How it works

Installing `zuplo` bundles the full Zuplo documentation at
`node_modules/zuplo/docs/`. The bundled docs cover policies, handlers, concepts,
guides, CLI reference, and more:

```txt
node_modules/zuplo/docs/
├── concepts/          # Core concepts (request lifecycle, project structure)
├── policies/          # Policy catalog, per-policy docs and JSON schemas
├── handlers/          # Handler docs (URL forward, custom handler, etc.)
├── articles/          # Guides (CORS, env vars, auth, deployment, etc.)
├── cli/               # CLI reference
├── dev-portal/        # Developer portal / Zudoku docs
├── guides/            # Step-by-step guides
└── programmable-api/  # Programmable API reference
```

This means agents always have access to docs that match your installed version
with no network request or external lookup required.

The `AGENTS.md` file at the root of your project tells agents to read these
bundled docs before writing any code. Most AI coding agents — including Claude
Code, Cursor, GitHub Copilot, Windsurf, and others — automatically read
`AGENTS.md` when they start a session.

## Getting started

### New projects

Creating a new project with `create-zuplo-api` generates the `AGENTS.md` and
`CLAUDE.md` files automatically. No additional setup is needed:

```bash
npx create-zuplo-api@latest
```

### Existing projects

Ensure you are on `zuplo` version `0.66.0` or later, then add the following
files to the root of your project.

`AGENTS.md` contains the instructions that agents read:

```md title="AGENTS.md"
# Zuplo: ALWAYS read docs before coding

Before any Zuplo work, find and read the relevant doc in
`node_modules/zuplo/docs/`. Your training data may be outdated — the bundled
docs are the source of truth.
```

`CLAUDE.md` uses the `@` import syntax to include `AGENTS.md`, so
[Claude Code](https://docs.anthropic.com/en/docs/claude-code) users get the same
instructions without duplicating content:

```md title="CLAUDE.md"
@AGENTS.md
```

## Understanding AGENTS.md

The default `AGENTS.md` contains a single, focused instruction: **read the
bundled docs before writing code**. This is intentionally minimal — the goal is
to redirect agents from stale training data to the accurate, version-matched
documentation in `node_modules/zuplo/docs/`.

The bundled docs include guides, API references, policy schemas, and handler
documentation. When an agent encounters a task involving routing, policies,
authentication, rate limiting, or any other Zuplo feature, it can look up the
correct configuration in the bundled docs rather than relying on potentially
outdated training data.

You can add your own project-specific instructions to `AGENTS.md` or `CLAUDE.md`
alongside the Zuplo defaults.

## Going further

Once `AGENTS.md` is in place, layer on the rest of Zuplo's agent tooling:

1. [**Install the official skills**](../build-with-ai/skills.md) for
   task-specific playbooks on project setup, policies, handlers, monetization,
   and more.
2. [**Add the Docs MCP server**](../build-with-ai/docs-mcp-server.md) for
   real-time search and Q&A across the full documentation.
3. [**Add the Zuplo MCP server**](../build-with-ai/zuplo-mcp-server.md) to let
   agents drive your Zuplo account — deploy, manage API keys, inspect logs, and
   more.

## Summary

The recommended setup, in priority order:

1. **Bundled docs** — always available at `node_modules/zuplo/docs/`,
   version-matched, no setup required beyond `AGENTS.md`.
2. **[Agent skills](../build-with-ai/skills.md)** — task-specific guidance from
   [`zuplo/tools`](https://github.com/zuplo/tools).
3. **[MCP servers](../build-with-ai/overview.md)** — real-time docs search and
   programmatic gateway management.