seedproject-web/.claude/skills/changelog/SKILL.md

name

description

changelog

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 an array of [type, summary, detail, 'YYYY-MM-DD HH:MM', by?] — the 5th element (by, the actor) is optional:

['added', 'Contact form wired up', 'Real submissions stored in the database, with validation and spam protection.', '2026-07-23 12:14'],
['updated', 'Hero spacing tightened', 'Trimmed the vertical rhythm on the homepage hero.', '2026-07-24 09:00', 'Website Designer Agent'],

• 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.
• by (optional, 5th element) — who made the change. The changelog shows it as "Added · 09:00 · by …". Attribute it to whoever actually did the work:
  • An agent attributes the entry to itself — the Web Designer agent uses 'Website Designer Agent'.
  • A change made by the site owner (e.g. directed through the Claude CLI) is 'Carlos Arias', which is also the default when the 5th element is omitted.
  • Only name an agent when that agent genuinely made the change. If the Web Designer didn't do it, it's 'Carlos Arias'.

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

# 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.