docs: add LEARNINGS.md and PR template for AI agent guidance

.github/pull_request_template.md

@@ -0,0 +1,31 @@
+<!--
+  Pull request template for token-deathclock.
+  AI agents: fill in every section. Do not delete headings.
+  See docs/LEARNINGS.md for the full agent checklist and categorised learnings.
+-->
+
+## Summary
+
+<!-- One paragraph: what problem does this PR solve and how? -->
+
+## Changes
+
+<!-- A checked-off list of every discrete change made. Add items as needed. -->
+
+- [ ] <!-- change 1 -->
+- [ ] <!-- change 2 -->
+
+## Agent Checklist
+
+<!-- Agents must verify every item before requesting review. -->
+
+- [ ] `npm run test:ci` passes (all unit tests green, coverage not decreased)
+- [ ] `npm run build && npm run test:e2e` passes (all E2E tests green)
+- [ ] No generated files committed (`script.js`, `styles.css`, `*-data.js`)
+- [ ] All dynamic `innerHTML` values pass through `escHtml()`
+- [ ] No DOM references introduced in `death-clock-core.js`
+- [ ] No new runtime npm packages added
+- [ ] GitHub Actions `uses:` pins use a full commit SHA + inline semver comment
+- [ ] PR title follows Conventional Commits (`feat:`, `fix:`, `docs:`, `chore:`, etc.)
+- [ ] `project-stats.yaml` updated if this session merges one or more PRs
+- [ ] Relevant entry added to `docs/LEARNINGS.md` (new pattern or lesson learned)

AGENTS.md

@@ -3,6 +3,13 @@
 This file gives AI coding agents (GitHub Copilot, Claude, ChatGPT, etc.) the context
 they need to work effectively on this repository.
 
+**Companion documents — read these too:**
+
+| File | Purpose |
+|------|---------|
+| [`docs/LEARNINGS.md`](docs/LEARNINGS.md) | Living log of lessons learned from past PRs, organised by category (mobile/CSS, build, testing, architecture, security, features). Add an entry after every merged PR. |
+| [`.github/pull_request_template.md`](.github/pull_request_template.md) | Standard PR description template. Every PR (human or agent) must follow this structure: Summary, Changes checklist, Agent Checklist. |
+
 ---
 
 ## Project Purpose
@@ -149,6 +156,13 @@ Edit the `MILESTONES` array in `death-clock-core.js`. Each object requires:
 `id`, `name`, `icon`, `tokens`, `shortDesc`, `description`, `consequence`, `followingEvent`, `color`, `darkColor`.
 Keep the array sorted in ascending `tokens` order — the constants test enforces this.
 
+### Documenting PR learnings
+After merging a PR, add a brief entry to [`docs/LEARNINGS.md`](docs/LEARNINGS.md)
+under the current release block using the template at the top of that file. If
+the PR reveals a new recurring pattern (e.g., a mobile layout gotcha, a build
+quirk), also add a row to the relevant table in the **Categorised Learnings**
+section so future agents can find it by topic.
+
 ### Updating project token consumption stats (footer)
 The footer shows how many tokens this project has consumed building itself.
 After each agent session that merges one or more PRs, **update `project-stats.yaml`**:
@@ -327,6 +341,7 @@ feat!: redesign anchor hash scheme (removes legacy ?tab= param)
 - Do **not** skip tests when adding new pure functions to the core module.
 - Do **not** change `BASE_TOKENS` / `TOKENS_PER_SECOND` / `BASE_DATE_ISO` independently — update all three as a set with a comment explaining the source.
 - Do **not** use mutable tags (e.g. `@v6`) in `uses:` — always pin to a commit SHA with a full semver comment (e.g. `@abc1234... # v6.0.2`).
+- Do **not** finish a session without adding a learning entry to `docs/LEARNINGS.md` for any PR merged in that session.
 - Do **not** finish a session without running `npm run test:ci` and `npm run test:e2e` to confirm both suites pass.
 - Do **not** let coverage decrease — a negative coverage delta on any PR fails the Codecov status check.
 - Do **not** edit `changelog-data.js`, `milestones-data.js`, or `project-stats-data.js` directly — they are auto-generated and in `.gitignore`; edit `CHANGELOG.md` / `milestones.yaml` / `project-stats.yaml` and run the corresponding build script.