EventCatalog 3.35.1 bundles the full documentation inside the npm package itself, giving AI coding agents a version-matched source of truth they can read before touching your catalog.
I've been using Claude Code and Cursor every day to work on EventCatalog, and I kept running into the same frustrating thing — the agent would confidently spit out frontmatter that didn't exist, point at folders we'd renamed months ago, or call an API that changed two releases back. I'd read the diff, sigh, and fix it by hand. Every time.
It's not really the agent's fault. It's working from a snapshot of the web that's months (or years) out of date, and EventCatalog moves fast. So I kept asking myself: why are we making agents guess what our API looks like when the answer is already sitting in node_modules?
That's what shipped in 3.35.1. The full EventCatalog docs are now bundled inside the npm package, version-matched to whatever you have installed. No more guessing. No more stale snippets. The agent reads the same docs you do.
The problem: agents work from a snapshot of the past
AI coding tools are trained on a snapshot of the web. EventCatalog's frontmatter conventions, folder layout, and APIs evolve with every release. So when you ask an agent to "add a new service to EventCatalog" or "create a domain", it reconstructs what it thinks the API looks like from training data that may be months or years behind.
The result is hallucinated frontmatter fields, wrong file paths, and subtle schema errors that only surface when you try to run the catalog. Fixing them by hand erases the time you saved using the agent in the first place.
What's new in 3.35.1
Starting in @eventcatalog/core v3.35.1, the complete EventCatalog documentation is bundled inside the npm package. After a normal install, the docs live at:
node_modules/@eventcatalog/core/dist/docs/
The structure mirrors the documentation website:
api/— Frontmatter reference for every resource typecli/— CLI commandsdevelopment/— Getting started, guides, customizationplugins/— Generator and plugin documentation
No extra install. No network request. No version mismatch. Upgrade @eventcatalog/core and the docs upgrade with it, automatically.
How to wire it up
New projects: already done
If you scaffold a new project with npx create-eventcatalog@latest, two files land in your project root automatically.
AGENTS.md is the open convention that most coding agents read before acting:
<!-- BEGIN:eventcatalog-agent-rules -->
# EventCatalog: ALWAYS read docs before coding
Before any EventCatalog work, find and read the relevant doc in `node_modules/@eventcatalog/core/dist/docs/`. Your training data may be outdated. The bundled docs are the source of truth.
<!-- END:eventcatalog-agent-rules -->
CLAUDE.md is a one-liner that re-exports those rules for Claude Code without duplicating content:
@AGENTS.md
That's it. Any agent that reads AGENTS.md (Cursor, Windsurf, GitHub Copilot, and others) or CLAUDE.md (Claude Code) will find the right docs before it generates anything.
Existing projects: two files
Add AGENTS.md and CLAUDE.md to your project root with the content shown above. The BEGIN/END markers inside AGENTS.md let you add your own project-specific instructions outside the managed block. Future EventCatalog releases will only update content inside those markers, so your additions stay safe.
Using targeted doc paths
When an agent needs to work on a specific resource type, point it at the relevant subdirectory directly rather than the whole docs tree. This keeps context focused and reduces noise.
For example, when adding a service:
- Read
dist/docs/api/04-service-api.mdfor the exact frontmatter schema - Read
dist/docs/development/guides/services/for the folder conventions
The same pattern applies to events, commands, domains, and flows. Match the doc to the task.
Why this matters in practice
No more hallucinated frontmatter. The agent reads the schema for the version you have installed, not a guess based on training data.
No network round-trips. The docs are already on disk. Agents read them as fast as any other local file, and they work fully offline.
Version-locked. The docs are part of the package, so they can't drift out of sync. There's no separate docs version to pin or manage.
Works with any agent. AGENTS.md is an open convention. It doesn't matter which tool your team uses — the instruction to read the local docs travels with the project.
What's next
Bundled docs are one part of a broader push to make EventCatalog a first-class AI-native tool. If you want to go further, the AI integration overview covers the full picture: the EventCatalog AI Assistant, the MCP server that lets agents query your catalog directly, Slack integration, and Skills. Each layer builds on the same idea — your catalog should be the source of truth for both humans and the agents working alongside them.