For AI agents

If an AI coding agent writes your plugins, give it the right context. Everything below is generated at build time from the repository (the C# XML docs and reflection metadata of Mc.Scripting.Api, src/scripting/events.json, the engine sources and the site pages), so it cannot disagree with the API it describes.

What is available

Resource	Where	What it is
/llms.txt	site root, docs-site/public/llms.txt	a short index in the llms.txt convention: what Ramjet is, the five rules that matter, and links with one-line descriptions
/llms-full.txt	site root, docs-site/public/llms-full.txt	the complete plugin-development documentation as one plain-markdown file: getting started, concepts, guides, the status and event reference, the sample plugins’ source, and the API reference
/api.json	site root, docs-site/public/api.json	machine-readable API: every public type and member with signature, summary, parameters, returns, examples; the event catalogue (fields, types, mutability, cancellability, engine firing sites); phases; event priorities; the vanilla command argument types; engine status (what is wired); native systems; the “hard rules”
Claude Code skill	.claude/skills/ramjet-plugin/	SKILL.md (when to use it, project setup, hard rules, recipes, how to test with a scratch server, where to look things up) and references/api.md, events.md, native-systems.md
AGENTS.md	in every project created from the template (templates/ramjet-plugin/)	the rules, build/run/test loop, and an event cheat sheet for agents working inside a plugin project; a one-line CLAUDE.md imports it, and the skill is copied into the project too

All of these are committed, and npm run check:gen (in docs-site/) fails when they are stale, so a change to the API without regenerating shows up in review.

How to use them

• Pasting context into a chat or an agent without file access: attach llms-full.txt (about 500 KB of text) or just the pages it names.
• An agent with a checkout of the repository: the skill loads on its own when the task looks like plugin work; or point it at .claude/skills/ramjet-plugin/SKILL.md.
• A new plugin project: dotnet new ramjet-plugin -n MyPlugin already contains AGENTS.md, CLAUDE.md and the skill, so agents opened in the project know the rules. The project references the Ramjet.Api package, whose reference assembly carries the API’s XML documentation, so an agent can read signatures and docs from the package itself.
• Tooling: api.json is stable, versioned ("schema": 1) and diff-friendly: use it for lint rules (for example “no $"" in a handler of an event with engineWired”), for code completion, or to check an agent’s claim (“is PlayerMoveEvent.To mutable?”) without reading prose.

The rules agents most often get wrong

The same six rules are in llms.txt, the skill, the template’s AGENTS.md and api.json (hardRules), generated from one place:

1. everything runs on the tick thread, Scheduler.Post is the only thread-safe entry;
2. event handlers get the event by ref and must not allocate on hot paths;
3. borrowed Utf8String/NativeBytes must be copied to be kept;
4. Entity is a handle: re-fetch refs after structural changes;
5. components are unmanaged structs owned by one plugin;
6. register through the plugin context so unloading and hot reload are exact.

And the one that is easy to miss: only part of the API is wired on main. The generated status page lists exactly which events fire and which host services are stubs; agents should read it (or status in api.json) before building a feature on a call that may only log.

Regenerating

cd docs-site
npm run gen          # api.json, API pages, content pages, llms*.txt, skill, template AGENTS.md
npm run check:gen    # fails if a committed generated file differs from the sources