diff --git a/AGENTS.md b/AGENTS.md
index 550cef6..8ca9d38 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -4,6 +4,12 @@
 
 The package is stateless, so loading the ESM and CJS builds in one process is safe.
 
+## Lit and render-template notes
+
+Parts must return strings. The package depends on `@llazyemail/render-template` (see `package.json`). Lit `TemplateResult` objects cannot be returned from a part `render` function. Consumers that still author with Lit keep a local `renderEmailBody` / `stripLitMarkers` step that produces a string, then feed that string into the shell helpers or `renderTemplate`.
+
+Do not vendor or reimplement the part/compose runtime; use the re-exports from this package or from `render-template` directly. Generation logic belongs in `@llazyemail/generate-template`.
+
 ## Commands
 
 ```bash
diff --git a/README.md b/README.md
index eb59165..c413f75 100644
--- a/README.md
+++ b/README.md
@@ -12,6 +12,14 @@ Requires **Node.js 24+**. No runtime dependencies. No template registry. Strings
 - Full API: [llms-full.txt](./llms-full.txt)
 - Sample: [examples/compose.ts](./examples/compose.ts)
 
+## Package ecosystem and Lit
+
+This package builds on `@llazyemail/render-template` (currently pinned via GitHub ref in `package.json`). Parts must return **strings**. Lit `TemplateResult`s are not supported inside parts.
+
+Consumers that still use Lit SSR (e.g. `_playing_with_lit`) keep a thin local adapter (`renderEmailBody` + `stripLitMarkers`) that turns a Lit result into a string, then pass that string into `document` / `renderTemplate` / `renderEmail`. Do not try to put Lit templates directly into a part `render` function — that is a known source of runtime errors.
+
+Generation/catalog/write logic belongs in `@llazyemail/generate-template`, not here.
+
 ## Install
 
 Published to GitHub Packages. Copy [`.npmrc.example`](./.npmrc.example) to `.npmrc` in the consuming project. `GITHUB_TOKEN` needs `read:packages`.