docs: add AGENTS.md and emphasize string-only part contract

AGENTS.md

@@ -0,0 +1,32 @@
+# Agent notes for render-template
+
+`@llazyemail/render-template` is the low-level deterministic part/compose renderer. Parts return strings. The package is stateless. It is the foundation under `@llazyemail/template-runtime-display`.
+
+## String-only contract
+
+Every part `render` function must return a string (or null/undefined, which become `''`). Returning a Lit `TemplateResult`, a Promise, or any other non-string is an error. This is the most common source of problems when mixing this runtime with Lit SSR.
+
+Consumers that author with Lit must convert the Lit result to a string *before* handing HTML to a part or to `compose`. Do not put Lit templates inside parts.
+
+## Ecosystem
+
+- This package owns the part execution, traces, and error modes (`throw` / `collect`).
+- `@llazyemail/template-runtime-display` adds email shell fragments and re-exports the runtime helpers.
+- `@llazyemail/generate-template` owns catalogs, payloads, and disk writes. Do not add generation logic here.
+
+## Commands
+
+```bash
+npm install
+npm run build
+npm test
+npm run typecheck
+```
+
+Node >= 22. CI runs on 22 and 24.
+
+## Layout
+
+See README.md for the tree. Public surface is `src/index.ts`.
+
+Do not add Lit as a dependency. Do not add I/O. Keep the package free of template catalogs.

README.md

@@ -10,6 +10,11 @@ returns the final HTML.
   optional `error`.
 - **Two error modes** — fail fast (`'throw'`) or collect-and-continue
   (`'collect'`).
+- **String parts only** — each part must return a string. Lit `TemplateResult`s,
+  Promises, or other non-strings are errors. Convert Lit output to a string
+  before it reaches a part.
+
+Working on this repo with an AI agent? Start at [AGENTS.md](./AGENTS.md).
 
 ## Install
 
@@ -76,6 +81,9 @@ All public types are re-exported from the package root:
 
 - `template-runtime-display` — email shell helpers (`defineEmailTemplate`,
   `renderEmail`) on top of this runtime.
+- `generate-template` — catalog, payload resolution, and disk writes. Consumers
+  should inject their render functions into `createGenerator` rather than
+  reimplementing generation logic.
 
 ## License