Agent handbook (not for humans)

You are a coding agent. The developer included ReScripted.h in their project, or they pointed you at this GitHub repo so you can generate a language.

Humans should use ../user/index.md. Do not send them here.

Read this file first. Then open every linked file that matches the task. Do not invent APIs, schema keys, or file locations.

---

What ReScripted is

ReScripted is a header-only C++17 library. One generated file: include/ReScripted.h.

Two different artifacts:

Artifact	Compiled into the C++ program?	Who owns it
Language config (JSON)	Yes. Must be in the user’s binary	The developer / you, in their repo
Scripts (source in that language)	No. Loaded, run, unloaded at runtime	Anyone using the language

You do not create the language inside the ReScripted repository unless the user is actually contributing to ReScripted itself.

---

Mandatory read order

When the user asks you to make a language:

1. consumer-workflow.md — where files go
2. language_template.json — schema contract
3. generating-a-language.md — how to fill the JSON
4. implemented-schema.md — what the engine actually honors today
5. custom-kinds.md — extra function kinds, types, decorators
6. checklist.md — before you say you are done

When the user asks you to wire ReScripted into their C++ app:

1. embedding-for-agents.md
2. runtime-api.md
3. host-bindings.md
4. value-and-errors.md
5. stdlib-design.md

When the user asks you to write or debug scripts in a language you already defined:

1. script-semantics.md
2. examples-and-recipes.md
3. pitfalls.md

When something fails:

1. validation-and-testing.md
2. pitfalls.md

---

Hard rules

• Preserve language_template.json structure. Change values only.
• Write ONE complete JSON. Do not invent a shorter schema.
• Keep disabled features present and disabled.
• Language JSON goes in the user’s project.
• That JSON is compiled in via Language::compile, RESCRIPTED_LANGUAGE(...), or rescripted_embed_language / scripts/embed_language.sh.
• Scripts are engine.load / load_file / run / call / unload / eval.
• Do not invent rescripted::language("file.json") that reads the config from disk as the official path.
• Do not add if (language.name == "Python") in ReScripted itself.
• Custom declarations the template cannot name go under custom.function_kinds, custom.types, custom.decorators, custom.host_functions.
• Host C++ decides what those names mean (bind, bind_type, bind_decorator).
• License of ReScripted is LGPL-3.0-or-later. Contact: contact@atechsoftware.com.

---

Canonical C++ surface (do not rename)

#include <ReScripted.h>

rescripted::Engine engine;
engine.add_language(rescripted::Language::compile(compiled_json_text));
engine.bind("name", host_fn);
engine.bind_type("entity", host_fn);
engine.bind_decorator("export", hook);
engine.add_library("app.math", rescripted::library::math);
engine.add_library("prelude", source, "MyLang");
engine.add_library_file("MyMod", "packages/MyMod/main.mylang");
engine.load_plugin("mods/extra.dylib");
auto id = engine.load(source, "npc.mylang", "MyLang");
auto id2 = engine.load_file("npc.mylang"); // extension picks the language
engine.run(id);
engine.call("think", {rescripted::Value("player")});
engine.unload(id);
engine.eval("print(1);", "MyLang");

Full method list: runtime-api.md.

---

File index

File	Purpose
AGENTS.md	This handbook
consumer-workflow.md	Work in the user’s repo, not this one
language_template.json	Canonical schema
generating-a-language.md	How to fill every section
implemented-schema.md	Engine coverage vs template
custom-kinds.md	User-defined declarations
embedding-for-agents.md	Compile the JSON into their app
runtime-api.md	Engine / Language / ScriptId
value-and-errors.md	Value types and exceptions
host-bindings.md	bind / types / decorators
libraries.md	add_library — CMake does not name packages
stdlib-design.md	Designing a host standard library
script-semantics.md	What the interpreter does
examples-and-recipes.md	Copy-shaped examples
validation-and-testing.md	How to prove the language works
pitfalls.md	Common agent mistakes
checklist.md	Done criteria