From 2ad551dc5fe5741cd3660a667cb8f662292dde21 Mon Sep 17 00:00:00 2001
From: Carlos Arias <hi@carlosarias.com>
Date: Fri, 24 Jul 2026 02:39:01 +0000
Subject: [PATCH] skills: add changelog skill (seed-changelog process, format,
 voice)

---
 .claude/skills/changelog/SKILL.md | 70 +++++++++++++++++++++++++++++++
 1 file changed, 70 insertions(+)
 create mode 100644 .claude/skills/changelog/SKILL.md

diff --git a/.claude/skills/changelog/SKILL.md b/.claude/skills/changelog/SKILL.md
new file mode 100644
index 0000000..5c15ece
--- /dev/null
+++ b/.claude/skills/changelog/SKILL.md
@@ -0,0 +1,70 @@
+---
+name: changelog
+description: Update the public changelog for the Carlos Arias site (carlosarias.co, the /changelog page). Use whenever asked to "update the changelog", "log a change", "add a changelog entry", or to record that something was added, updated, fixed, or found broken. The changelog is a curated narrative seeded from api/cli/seed-changelog.php into the cja_changelog table and read at build time — this skill covers the exact entry format, the valid types, the voice, and the reseed + rebuild steps.
+---
+
+# Skill: update the changelog
+
+The public changelog (`/changelog`) is a **curated narrative**, not an accreting log. Its
+single source of truth is the `$entries` array in **`api/cli/seed-changelog.php`**. That
+script **TRUNCATEs and reloads** the `cja_changelog` table every run, and the static site
+reads that table **at build time** (`app/src/lib/changelog.js`). So the process is always:
+
+1. **Edit** `api/cli/seed-changelog.php` — append (or amend) entries in the `$entries` array.
+2. **Reseed** the table: `php api/cli/seed-changelog.php`
+3. **Rebuild** the site so `/changelog` reflects it.
+
+Editing the file alone changes nothing live — steps 2 and 3 are required.
+
+## Entry format
+
+Each entry is a 4-element array: `[type, summary, detail, 'YYYY-MM-DD HH:MM']`
+
+```php
+['added', 'Contact form wired up', 'Real submissions stored in the database, with validation and spam protection.', '2026-07-23 12:14'],
+```
+
+- **type** — one of: `added`, `updated`, `fixed`, `bug`, `removed`, `note`.
+  Use `bug` to record that something broke, and a paired `fixed` for the repair (see the
+  existing bug→fixed pairs for the pattern).
+- **summary** — the headline (≤ 255 chars). Sentence case, no trailing period.
+- **detail** — one sentence of context (≤ 500 chars), or `null` for none. Ends with a period.
+- **timestamp** — `'YYYY-MM-DD HH:MM'` (seconds are appended automatically). **This is what
+  orders the timeline** — the page shows entries newest-first by this value, not by array
+  position — so a new entry can go anywhere in the array as long as its timestamp is right.
+  Use the real date/time the change happened; if unknown, use now.
+
+## Voice
+
+Match the existing entries: **write for a visitor, not for the repo.** Describe what changed
+on the site from a reader's point of view, in plain past tense. Concise, understated, no hype,
+no exclamation marks, British-leaning spelling ("optimised", "colour") to match the set.
+
+- Good: `['added', 'Project galleries and social rail', 'A photo gallery with a lightbox, and a sticky Instagram rail beside each case study.', '...']`
+- Avoid internal mechanics: not "Added a getStaticPaths loop over cja_projects" but "Per-project case-study pages generated from the database."
+- One change = one entry. A bug and its fix are two entries (a `bug` then a `fixed`).
+
+## Steps in full
+
+```bash
+# 1. edit api/cli/seed-changelog.php — add your entry to the $entries array
+
+# 2. reseed the table (truncate + reload the curated set)
+php api/cli/seed-changelog.php          # prints "seeded N changelog entries"
+
+# 3. rebuild so /changelog is live
+#    - preferred: the console runner rebuilds (POST /devconsole/rebuild), OR
+#    - direct (never as root — build as the site owner):
+cd app && npm run build
+```
+
+## Constraints & gotchas
+
+- **Don't INSERT rows directly** into `cja_changelog` — the next reseed would wipe them. The
+  seed file is the source of truth; always edit it.
+- **Never build as root** — it leaves root-owned files that break later builds. Build via the
+  runner or as the site's agent user (see `agents/console/SETUP.md`).
+- **No shell? (confined headless agent)** — you can still do step 1 (edit the seed file with
+  Write/Edit), but you cannot run steps 2–3. In that case, make the edit and clearly report
+  that `php api/cli/seed-changelog.php` + a rebuild are still needed for it to go live.
+- The `detail` column is capped at 500 chars and `summary` at 255 — keep both tight.