docs: add an agent playbook and keep agent docs in sync with action.yml

.github/workflows/render-email-template.yml

@@ -5,6 +5,9 @@ on:
     paths:
       - action.yml
       - README.md
+      - AGENTS.md
+      - llms.txt
+      - docs/**
       - scripts/**
       - tests/check-action.py
       - .github/workflows/**
@@ -13,6 +16,9 @@ on:
     paths:
       - action.yml
       - README.md
+      - AGENTS.md
+      - llms.txt
+      - docs/**
       - scripts/**
       - tests/check-action.py
       - .github/workflows/**

AGENTS.md

@@ -16,6 +16,19 @@ Guidance for AI coding agents that work **in** this repository, or that **add th
 
 Current tag to use from other repos: `LLazyEmail/email-template-workflows@v1`.
 
+## Start here
+
+- **Adding this Action to another repository?** Follow [`docs/agent-playbook.md`](docs/agent-playbook.md): inspect the repo, choose a mode, write the workflow, verify. It has copy-paste recipes and a table that maps log messages to fixes.
+- **Changing this repository?** Skip to [Working on this repository](#working-on-this-repository).
+
+The five rules that matter most when adding the Action:
+
+1. Look at the repository first (lockfile, `package.json` scripts, template files, `.npmrc`, existing workflows). Never invent a script, flag, path or input.
+2. Pick one render mode: `command` (one command renders everything), `build-command` (a CLI renders one file; use `$EMAIL_TEMPLATE_INPUT` and `$EMAIL_TEMPLATE_OUTPUT`), or `build-script` (an npm script takes input and output paths).
+3. Set `working-directory` (the default `generated` is rarely right) and `artifact-directory` (where the HTML really is). Paths are relative to `working-directory`.
+4. Pin `@v1`, put `actions/checkout` first, and give every call its own `artifact-name`.
+5. Do not report success until a pull request run shows the artifact, the job summary and a single `### Rendered emails` comment, or say plainly that you could not check.
+
 ## Adding the Action to another repository: decision rules
 
 Follow in order and stop at the first match.
@@ -74,13 +87,7 @@ Outputs: `html-path` (first rendered file), `html-count`, `failed-count`, `artif
 
 ## Verifying a change
 
-After adding or editing a caller workflow:
-
-1. Confirm the workflow YAML is valid and the `uses:` line is `LLazyEmail/email-template-workflows@v1`.
-2. Confirm every package script named in `build-script` (and `validate-script`) exists in the consumer's `package.json`.
-3. Confirm `artifact-directory` matches where the build actually writes.
-4. Confirm permissions match the table above.
-5. Push to a branch and open a pull request; the run should show an artifact named `artifact-name`, a job summary, and a single `### Rendered emails` comment.
+Step 4 of the [playbook](docs/agent-playbook.md#step-4-verify) is the checklist: the YAML parses, the scripts and paths exist, `artifact-directory` matches the build, permissions fit, and a pull request run shows an artifact, a job summary and one `### Rendered emails` comment.
 
 ## Working on this repository
 
@@ -103,4 +110,5 @@ After adding or editing a caller workflow:
 - Real consumer: `LLazyEmail/_playing_with_lit` → `.github/workflows/render-email-action.yml` (explained in `docs/real-world-example.md`)
 
 ## Failure annotations
-A non-zero build, validation, or command exits with an `::error::` annotation. The annotation includes the first cause line from the command (for example `error TS2307: Cannot find module ...`), and the failure block reprints that cause plus the last 20 lines.
+
+A non-zero build, validation or command exits with an `::error::` annotation. The annotation includes the first cause line from the command (for example `error TS2307: Cannot find module ...`), and the failure block reprints that cause plus the last 20 lines. The playbook's [troubleshooting table](docs/agent-playbook.md#when-something-goes-wrong) maps each message to a fix.

CHANGELOG.md

@@ -4,6 +4,11 @@ All notable changes to `LLazyEmail/email-template-workflows` are listed here.
 
 ## [Unreleased]
 
+### Added (agent documentation)
+- `docs/agent-playbook.md`: a step-by-step procedure for AI agents that add the Action to a repository (inspect, choose a mode, write the workflow, verify), a decision flowchart, eleven recipes, a table that maps log messages to fixes, and hard rules.
+- `AGENTS.md` now opens with a "Start here" section and the five rules that matter most.
+- `tests/check-action.py` checks every YAML snippet in the README and the playbook: it must parse, and any call to this Action may only use inputs that exist in `action.yml`. It also checks that relative links in the docs point at files that exist.
+
 ### Added (universal support)
 - Package managers: `package-manager` (`auto`, `npm`, `yarn`, `pnpm`, `bun`) and `package-manager-version`. `auto` reads the `packageManager` field, then the lockfile in `working-directory` and its parents (monorepos), then falls back to npm. yarn and pnpm run through Corepack, bun through `oven-sh/setup-bun`.
 - `build-command` and `validate-command`: run any tool once per template, with `EMAIL_TEMPLATE_INPUT` and `EMAIL_TEMPLATE_OUTPUT` set. These variables are now set for `build-script` and `validate-script` too.

README.md

@@ -88,6 +88,7 @@ steps:
 
 ## For AI agents and LLM tools
 
+- [`docs/agent-playbook.md`](docs/agent-playbook.md): start here. Inspect the repository, choose a mode, write the workflow, verify. Copy-paste recipes and a table that maps log messages to fixes.
 - [`llms.txt`](llms.txt): short index of this repository for LLMs.
 - [`AGENTS.md`](AGENTS.md): decision rules, input precedence, gotchas and a verification checklist for agents that add this Action to a repository.
 - [`action.yml`](action.yml): source of truth for inputs, outputs and defaults.
@@ -207,7 +208,7 @@ Your own `env:` on the job is passed through as usual, so secrets such as `NODE_
 bash tests/detect-package-manager.test.sh   # package manager, lockfile and cache resolution
 bash tests/render.test.sh                   # every render mode, with each installed package manager
 node tests/pr-comment.test.js               # the pull request comment, with a mocked GitHub client
-python3 tests/check-action.py               # action.yml, README and pinned actions stay in sync
+python3 tests/check-action.py               # action.yml, docs, snippets, links and pinned actions stay in sync
 ```
 
 CI runs these on Linux, macOS (including the system bash 3.2) and Windows, lints the YAML, shell scripts and workflows (`yamllint`, `shellcheck`, `actionlint`), and renders `fixtures/consumer` through `uses: ./` with each package manager. `.github/workflows/fixture-render.yml` has one job per capability.