diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..48f0691
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,16 @@
+# Agent notes
+
+This repository holds one Ansible playbook per service. Read
+[CODING_STANDARDS.md](CODING_STANDARDS.md) before adding or changing a playbook.
+
+- Layout and naming: [CODING_STANDARDS.md](CODING_STANDARDS.md).
+- Checks: run `./scripts/check.sh`. It runs yamllint, ansible-lint, and a syntax
+  check on every `*/playbook.yml`. CI runs the same script.
+- Review baseline: `origin/main`. The review diff is `git diff origin/main...HEAD`.
+- Migration spec: [docs/podman-migration.md](docs/podman-migration.md). Section 8
+  lists the repo changes the migration expects.
+- Issue tracker: [docs/agents/issue-tracker.md](docs/agents/issue-tracker.md).
+- Scratch files: write them under `.scratch/`. It is git-ignored, and `/tmp` is
+  wiped between tool calls in this environment.
+- Secrets: `vars/default.yml` holds deploy values, including passwords. Do not
+  copy a production value into a file you push to a public remote.
diff --git a/CODING_STANDARDS.md b/CODING_STANDARDS.md
new file mode 100644
index 0000000..12f53e8
--- /dev/null
+++ b/CODING_STANDARDS.md
@@ -0,0 +1,80 @@
+# Coding standards
+
+Rules a reviewer applies to a diff. Anything a tool can check lives in
+`.yamllint`, `.ansible-lint`, or `scripts/check.sh`. This file covers the calls a
+tool cannot make.
+
+## Layout
+
+A service directory is either flat or role-based. Pick by the service, not by
+taste.
+
+Use the flat layout for one container plus a proxy:
+
+```
+service/
+├── files/
+├── vars/
+│   └── default.yml
+├── playbook.yml
+└── readme.md
+```
+
+Use roles when the service has more than one container, unit, or stateful volume:
+
+```
+service/
+├── roles/
+│   ├── network/
+│   ├── storage/
+│   └── service/
+├── vars/
+│   └── default.yml
+├── playbook.yml
+└── readme.md
+```
+
+`playbook.yml` lists roles in dependency order. The data tier goes first, the app
+next, and the edge last. Each role has `tasks/main.yaml`. Add
+`handlers/main.yaml` and `templates/` only when the role needs them.
+
+## Naming
+
+- `playbook.yml`, `vars/default.yml`, and `readme.md` in every service directory.
+- Role task and handler files use `main.yaml`. Playbook and vars files use `.yml`.
+  This matches the existing tree. Do not rename either set in an unrelated change.
+- Handler names describe the action, for example "Restart Caddy", not the trigger.
+
+## YAML
+
+- Two-space indent, no tabs, LF line endings.
+- Quote Jinja values only when YAML would misread them.
+- Task names are sentence case and specific. "Create the data directory" is
+  better than "Create directory".
+
+## Tasks
+
+- Prefer a module to `command` or `shell`. When a command is necessary, add
+  `creates`, `changed_when`, or `failed_when` so a second run reports no change.
+- Put a long command string in `files/` or a template.
+- A task that writes a config file notifies a handler. It does not restart the
+  container inline.
+- Do not add `ignore_errors` to silence a check. Fix the task or narrow it.
+
+## Variables
+
+- Every variable a playbook needs has a value in `vars/default.yml` or a comment
+  naming the host fact that supplies it.
+- Quote passwords so a leading `0` or a `#` survives YAML.
+- `vars/default.yml` is where this repo keeps deploy values, including passwords.
+  Treat that file as sensitive. Rotate any value that leaks.
+
+## README
+
+Each `readme.md` states what the playbook deploys, the variables the operator
+must set, and the command to run it. Link the upstream image or project.
+
+## Commits
+
+One logical change per commit. Sentence case, imperative. Reference the issue
+when there is one, for example `Closes #12`.
diff --git a/README.md b/README.md
index 505793b..9a7bd5e 100644
--- a/README.md
+++ b/README.md
@@ -13,14 +13,12 @@ _\*the Initial Server Setup should be your starting point for fresh servers._
 
 ## Playbook Structure
 
-The playbooks contained in this repository were created for educational purposes, and should serve as a base for you to create your own playbooks and roles.
+Each service gets its own directory. A single-container service uses the flat layout below. A service with more than one container, unit, or stateful volume uses `roles/`. [CODING_STANDARDS.md](CODING_STANDARDS.md) states the rule and the naming conventions.
 
-Although we opt to not use roles, our playbooks follow a distinctive structure to facilitate reuse while keeping them mostly self-contained and straightforward.
-
-For instance, this is how the `lemp` playbook is structured:
+For instance, this is the flat layout:
 
 ```
-lemp_ubuntu1804
+service
 ├── files
 │   ├── info.php.j2
 │   └── nginx.conf.j2
@@ -31,10 +29,10 @@ lemp_ubuntu1804
 ```
 
 
-- `files/`: directory containing templates and other files required by the playbook.
-- `vars/`: directory to save variable files. A `default.yml` var file is included by default.
+- `files/`: templates and static files the playbook copies or templates.
+- `vars/`: variable files. `default.yml` holds the values the operator sets.
 - `playbook.yml`: the playbook file.
-- `readme.md`: instructions and links related to this playbook.
+- `readme.md`: what the playbook deploys, the variables to set, and the command to run it.
 
 ## Getting Started
 
diff --git a/docs/agents/issue-tracker.md b/docs/agents/issue-tracker.md
new file mode 100644
index 0000000..5e9e08a
--- /dev/null
+++ b/docs/agents/issue-tracker.md
@@ -0,0 +1,40 @@
+# Issue tracker
+
+The tracker is the Gitea instance at https://git.tanshu.com/tanshu/playbooks.
+Issues live under the Issues tab of that repository.
+
+## Fetching an issue
+
+Set a token once. Create one at https://git.tanshu.com/user/settings/applications
+with the `read:issue` scope.
+
+    export GITEA_TOKEN=...
+
+Then read one issue and its comments:
+
+    curl -s -H "Authorization: token $GITEA_TOKEN" \
+      https://git.tanshu.com/api/v1/repos/tanshu/playbooks/issues/123
+
+    curl -s -H "Authorization: token $GITEA_TOKEN" \
+      https://git.tanshu.com/api/v1/repos/tanshu/playbooks/issues/123/comments
+
+The JSON carries `title` and `body`. Pass those to the spec reviewer.
+
+## Finding the issue for a change
+
+Commit messages reference issues as `#123`. Check the commits under review:
+
+    git log --oneline origin/main..HEAD
+
+If no message references an issue, ask the user for the issue number. Do not
+guess.
+
+## Specs without an issue
+
+Larger changes use a plan in `docs/` instead of an issue. The Podman migration
+plan is `docs/podman-migration.md`. Section 8 lists the repo changes it expects.
+
+## Private or missing tracker
+
+If the host is unreachable or the token is absent, say so and fall back to a spec
+file under `docs/`. Do not invent requirements.